Ensure buttonRef.current.click() works (#3768)

This PR fixes an issue where adding a ref to the `<MenuButton
ref={btnRef}>` and later calling `btnRef.current.click()` would not open
the `Menu`.

This is happening because recently we started using `pointerdown`
instead of `click` to open the `Menu`. So the only way to open the
`Menu` programmatically is to call `btnRef.current.dispatchEvent(new
PointerEvent('pointerdown', { bubbles: true }))` which is a bit of a
mouthful.

We also recently fixed an issue where the `Listbox` would immediately
close after opening the Listbox on touch devices. That solution required
us to not only handle the `pointerdown` event but also the `click`
event.

So if anything, this PR makes the code more consistent between the
`Menu` and `Listbox` component behavior and in turn solves this
`ref.current.click()` issue.

This PR also does some internal refactoring to make the code a bit
cleaner.

Fixes: #3749

Author: RobinMalfait

packages/@headlessui-react/CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Fix incorrect double invocation of menu items, listbox options and combobox options ([#3766](https://github.com/tailwindlabs/headlessui/pull/3766))
 - Fix memory leak in SSR environment ([#3767](https://github.com/tailwindlabs/headlessui/pull/3767))
+- Ensure programmatic `.click()` on `MenuButton` ref works ([#3768](https://github.com/tailwindlabs/headlessui/pull/3768))
 
 ## [2.2.6] - 2025-07-24
 

packages/@headlessui-react/src/components/listbox/listbox.test.tsx

@@ -1,5 +1,5 @@
-import { render, waitFor } from '@testing-library/react'
-import React, { Fragment, createElement, useEffect, useState } from 'react'
+import { act, render, waitFor } from '@testing-library/react'
+import React, { Fragment, createElement, createRef, useEffect, useState } from 'react'
 import {
   ListboxMode,
   ListboxState,
@@ -1233,6 +1233,40 @@ describe('Rendering', () => {
       expect(handleChange).toHaveBeenNthCalledWith(2, 'bob')
     })
   })
+
+  it(
+    'should be possible to open a listbox programmatically via .click()',
+    suppressConsoleLogs(async () => {
+      let btnRef = createRef<HTMLButtonElement>()
+
+      render(
+        <Listbox>
+          <ListboxButton ref={btnRef}>Trigger</ListboxButton>
+          <ListboxOptions>
+            <ListboxOption value="a">Option A</ListboxOption>
+            <ListboxOption value="b">Option B</ListboxOption>
+            <ListboxOption value="c">Option C</ListboxOption>
+          </ListboxOptions>
+        </Listbox>
+      )
+
+      assertListboxButton({ state: ListboxState.InvisibleUnmounted })
+      assertListbox({ state: ListboxState.InvisibleUnmounted })
+
+      // Open listbox
+      act(() => btnRef.current?.click())
+
+      // Verify it is open
+      assertListboxButton({ state: ListboxState.Visible })
+      assertListbox({ state: ListboxState.Visible })
+      assertListboxButtonLinkedWithListbox()
+
+      // Verify we have listbox options
+      let options = getListboxOptions()
+      expect(options).toHaveLength(3)
+      options.forEach((option) => assertListboxOption(option))
+    })
+  )
 })
 
 describe('Rendering composition', () => {

packages/@headlessui-react/src/components/listbox/listbox.tsx

@@ -15,6 +15,7 @@ import React, {
   type ElementType,
   type MutableRefObject,
   type KeyboardEvent as ReactKeyboardEvent,
+  type MouseEvent as ReactMouseEvent,
   type PointerEvent as ReactPointerEvent,
   type Ref,
 } from 'react'
@@ -435,12 +436,7 @@ function ButtonFn<TTag extends ElementType = typeof DEFAULT_BUTTON_TAG>(
     }
   })
 
-  let pointerTypeRef = useRef<'touch' | 'mouse' | 'pen' | null>(null)
-  let handlePointerDown = useEvent((event: ReactPointerEvent) => {
-    pointerTypeRef.current = event.pointerType
-
-    if (event.pointerType !== 'mouse') return
-
+  let toggle = useEvent((event: ReactPointerEvent | ReactMouseEvent) => {
     if (event.button !== MouseButton.Left) return // Only handle left clicks
     if (isDisabledReactIssue7711(event.currentTarget)) return event.preventDefault()
     if (machine.state.listboxState === ListboxStates.Open) {
@@ -452,18 +448,16 @@ function ButtonFn<TTag extends ElementType = typeof DEFAULT_BUTTON_TAG>(
     }
   })
 
-  let handleClick = useEvent((event: ReactPointerEvent) => {
-    if (pointerTypeRef.current === 'mouse') return
+  let pointerTypeRef = useRef<'touch' | 'mouse' | 'pen' | null>(null)
+  let handlePointerDown = useEvent((event: ReactPointerEvent) => {
+    pointerTypeRef.current = event.pointerType
+    if (event.pointerType !== 'mouse') return
+    toggle(event)
+  })
 
-    if (event.button !== MouseButton.Left) return // Only handle left clicks
-    if (isDisabledReactIssue7711(event.currentTarget)) return event.preventDefault()
-    if (machine.state.listboxState === ListboxStates.Open) {
-      flushSync(() => machine.actions.closeListbox())
-      machine.state.buttonElement?.focus({ preventScroll: true })
-    } else {
-      event.preventDefault()
-      machine.actions.openListbox({ focus: Focus.Nothing })
-    }
+  let handleClick = useEvent((event: ReactMouseEvent) => {
+    if (pointerTypeRef.current === 'mouse') return
+    toggle(event)
   })
 
   // This is needed so that we can "cancel" the click event when we use the `Enter` key on a button.

packages/@headlessui-react/src/components/menu/menu.test.tsx

@@ -1,5 +1,5 @@
-import { render, waitFor } from '@testing-library/react'
-import React, { Fragment, createElement, useEffect } from 'react'
+import { act, render, waitFor } from '@testing-library/react'
+import React, { Fragment, createElement, createRef, useEffect } from 'react'
 import {
   MenuState,
   assertActiveElement,
@@ -542,6 +542,40 @@ describe('Rendering', () => {
     // Verify that the third menu item is active
     assertMenuLinkedWithMenuItem(items[2])
   })
+
+  it(
+    'should be possible to open a menu programmatically via .click()',
+    suppressConsoleLogs(async () => {
+      let btnRef = createRef<HTMLButtonElement>()
+
+      render(
+        <Menu>
+          <MenuButton ref={btnRef}>Trigger</MenuButton>
+          <MenuItems>
+            <MenuItem as="a">Item A</MenuItem>
+            <MenuItem as="a">Item B</MenuItem>
+            <MenuItem as="a">Item C</MenuItem>
+          </MenuItems>
+        </Menu>
+      )
+
+      assertMenuButton({ state: MenuState.InvisibleUnmounted })
+      assertMenu({ state: MenuState.InvisibleUnmounted })
+
+      // Open menu
+      act(() => btnRef.current?.click())
+
+      // Verify it is open
+      assertMenuButton({ state: MenuState.Visible })
+      assertMenu({ state: MenuState.Visible })
+      assertMenuButtonLinkedWithMenu()
+
+      // Verify we have menu items
+      let items = getMenuItems()
+      expect(items).toHaveLength(3)
+      items.forEach((item) => assertMenuItem(item))
+    })
+  )
 })
 
 describe('Rendering composition', () => {

packages/@headlessui-react/src/components/menu/menu.tsx

@@ -72,6 +72,7 @@ import {
 import { useDescriptions } from '../description/description'
 import { Keys } from '../keyboard'
 import { useLabelContext, useLabels } from '../label/label'
+import { MouseButton } from '../mouse'
 import { Portal } from '../portal/portal'
 import { ActionTypes, ActivationTrigger, MenuState, type MenuItemDataRef } from './menu-machine'
 import { MenuContext, useMenuMachine, useMenuMachineContext } from './menu-machine-glue'
@@ -265,8 +266,8 @@ function ButtonFn<TTag extends ElementType = typeof DEFAULT_BUTTON_TAG>(
     select: useCallback((target) => target.click(), []),
   })
 
-  let handlePointerDown = useEvent((event: ReactPointerEvent) => {
-    if (event.button !== 0) return // Only handle left clicks
+  let toggle = useEvent((event: ReactPointerEvent) => {
+    if (event.button !== MouseButton.Left) return // Only handle left clicks
     if (isDisabledReactIssue7711(event.currentTarget)) return event.preventDefault()
     if (disabled) return
     if (menuState === MenuState.Open) {
@@ -282,6 +283,18 @@ function ButtonFn<TTag extends ElementType = typeof DEFAULT_BUTTON_TAG>(
     }
   })
 
+  let pointerTypeRef = useRef<'touch' | 'mouse' | 'pen' | null>(null)
+  let handlePointerDown = useEvent((event: ReactPointerEvent) => {
+    pointerTypeRef.current = event.pointerType
+    if (event.pointerType !== 'mouse') return
+    toggle(event)
+  })
+
+  let handleClick = useEvent((event: ReactPointerEvent) => {
+    if (pointerTypeRef.current === 'mouse') return
+    toggle(event)
+  })
+
   let { isFocusVisible: focus, focusProps } = useFocusRing({ autoFocus })
   let { isHovered: hover, hoverProps } = useHover({ isDisabled: disabled })
   let { pressed: active, pressProps } = useActivePress({ disabled })
@@ -311,6 +324,7 @@ function ButtonFn<TTag extends ElementType = typeof DEFAULT_BUTTON_TAG>(
       onKeyDown: handleKeyDown,
       onKeyUp: handleKeyUp,
       onPointerDown: handlePointerDown,
+      onClick: handleClick,
     },
     focusProps,
     hoverProps,