Improve quick release by requiring some cursor movement (#3762)

This PR improves the quick release feature we have for Menu, Listbox and
Combobox components. This now ensures that your mouse was moved at least
`5px` before triggering the quick release action.

This odd behavior is most prevalent in Listbox components where the
`anchor="selection"` feature is used such that the options are rendered
on top of the Listbox button. Because of this, if you hold your cursor a
bit too long when clicking the Listbox it would immediately select the
option and close again.

With this improvement in place, you have to at least move your cursor
`5px`. This is an arbitrary value I picked so we can tweak it if we
wanted to, but `1px` to `3px` felt too small and `10px` felt too large.

### Test plan

When initially opening the Listbox, I'm holding down my cursor a bit
(but not moving!) and then releasing the "click".

#### Before:

Notice how the initial click results in the Listbox closing again once I
release the cursor.


https://github.com/user-attachments/assets/df8dc749-ce20-46c9-8815-ac817b789b7e

#### After:

Notice how the initial click results in the Listbox staying open even
after releasing the cursor. This is because we didn't move enough so we
don't register it as a quick release.


https://github.com/user-attachments/assets/f8d76a7b-1edd-4d9a-a8d3-120aadf49c57

Author: RobinMalfait

packages/@headlessui-react/CHANGELOG.md

@@ -7,7 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-- Nothing yet!
+### Fixed
+
+- Fix immediately closing Listbox by requiring some cursor movement ([#3762](https://github.com/tailwindlabs/headlessui/pull/3762))
 
 ## [2.2.5] - 2025-07-23
 

packages/@headlessui-react/src/hooks/use-quick-release.ts

@@ -28,6 +28,10 @@ export const Action = {
 // Pointerdown -> drag over an item -> pointer up -> "click" on the item
 const POINTER_HOLD_THRESHOLD = 200
 
+// We should at least move this amount of pixels before we consider it a quick
+// release. Otherwise it's just a normal click.
+const POINTER_MOVEMENT_THRESHOLD = 5
+
 type PointerEventWithTarget = Exclude<PointerEvent, 'target'> & {
   target: HTMLElement
 }
@@ -54,10 +58,15 @@ export function useQuickRelease(
   // Capture the timestamp of when the `pointerdown` event happened on the
   // trigger.
   let triggeredAtRef = useRef<Date | null>(null)
+  let startXRef = useRef<number | null>(null)
+  let startYRef = useRef<number | null>(null)
   useDocumentEvent(enabled && trigger !== null, 'pointerdown', (e) => {
     if (!DOM.isNode(e?.target)) return
     if (!trigger?.contains(e.target)) return
 
+    startXRef.current = e.x
+    startYRef.current = e.y
+
     triggeredAtRef.current = new Date()
   })
 
@@ -68,6 +77,15 @@ export function useQuickRelease(
       if (triggeredAtRef.current === null) return
       if (!DOM.isHTMLorSVGElement(e.target)) return
 
+      // Ensure we moved the pointer a bit before considering it a quick
+      // release.
+      if (
+        Math.abs(e.x - (startXRef.current ?? e.x)) < POINTER_MOVEMENT_THRESHOLD &&
+        Math.abs(e.y - (startYRef.current ?? e.y)) < POINTER_MOVEMENT_THRESHOLD
+      ) {
+        return
+      }
+
       let result = action(e as PointerEventWithTarget)
 
       let diffInMs = new Date().getTime() - triggeredAtRef.current.getTime()