useGestureRecognizer@astryxdesign/core v0.7.5 · useGestureRecognizer

Usage

Experimental: this hook may change or be removed in a patch release. Attaches a gesture recognizer with UIKit semantics to an element. Recognizers on the same touch arbitrate like UIKit: one wins unless you allow simultaneous recognition, requireToFail makes one wait for another, and a recognizer that takes a touch cancels the press and swallows the click underneath it. The element gets the touch-action its recognizers need before the first touch can land (pinch-zoom stays available unless a pinch or rotation recognizer is attached), and a claimed touch never scrolls the page. Thresholds and readings (the pan's 10 pt hysteresis, velocity(), a long press at 0.5 s) follow measurements of UIKit on iOS.

ts
import {useGestureRecognizer} from '@astryxdesign/core'

Best practices

GuidancePractices
Do

Drive the visual change from the listener by writing styles (a transform, an opacity) on the element; keep React state for the outcome only, such as dismissed or the snapped detent.

Do

Constrain a pan with direction (for example vertical for a sheet) so the browser keeps scrolling the other axis.

Do

Use requireToFail for a single tap that must wait for a double tap, as UIKit does.

Don't

Call setState on every changed callback; it renders on every move and drops frames.

Don't

Set touch-action: none on the element by hand; it disables pinch-zoom and fights the derived value.

Parameters

ParamTypeDescription
refrequired
RefObject<Element | null>

The element the recognizer watches. Touches that start on it or on its descendants reach the recognizer.

createrequired
() => R

Creates the recognizer, once for the life of the component (for example () => new PanGestureRecognizer({direction: "vertical"})). Set up relationships such as requireToFail and recognizeSimultaneouslyWith here or right after, since the instance never changes.

onGesture
(recognizer: R) => void

Called on began, changed, ended and cancelled, inside the input event. Read the recognizer (state, translation(), velocity(), scale, …) and write to the DOM directly; no React render happens per move. A new function each render re-attaches nothing.

options.isEnabled
boolean (default: true)

Live toggle. Turning it off during a gesture cancels the gesture.

options.manageStyle
boolean (default: true)

Lets the gesture system set the element's touch-action (and, for a long press, the iOS callout and text selection) from its recognizers. Turn it off only when the element's styles already say what the browser may do.

Returns

FieldTypeDescription
recognizerR

The recognizer instance, stable across renders. Use it to relate recognizers to each other or to read its state outside the listener.

Use with shadcn

Already using the shadcn registry workflow? Install the real Astryx package and a local public re-export. Component implementation source stays in Astryx.

This install URL expires with the draft preview.
bash
npx shadcn@4.19.0 add https://astryx-3qn36bhn6-fbopensource.vercel.app/shadcn/hooks/use-gesture-recognizer.json