usePress

Respond to press interactions.

Listen to pointer and keyboard “press” events on the element. This hook provides an accessible way to listen to press interactions from all modality types. The onPress callback is called with the native click event, which means it may be called in isolation (by assistive technology, etc.) and it may not be bookended by onPressStart and onPressEnd.

The usePress hook addresses certain UX issues related to click interactions. For example, if text is selected by a moving pointer while it is pressing, the press event is cancelled and the native behavior is prevented. This ensures that users can select text in a pressable region without triggering a press or navigation. A non-moving long press will have the same effect, as well as cancelling the native context menu on mobile. (This hook is implemented with useResponder and useKeyboard.)

import { usePress } from 'react-gui/use-press';

const ref = usePress(pressProps);

API #

Return value #

usePress returns a React callback ref.

ref (?HTMLElement) => void

A callback ref that must be passed to the target element.

PressProps #

delayLongPress ?boolean

How long to wait before onLongPress is called.

disabled ?boolean

Disable the hook.

onLongPress ?() => void

Called when the pointer has been down as long as delayLongPress, without moving more than 10px.

onPress ?(event: MouseEvent) => void

Called when the pointer has been successfully released (i.e., has dispatched a click event). It will not be called if text was selected during the gesture.

onPressCancel ?(event: PointerEvent) => void

Called when the pointer is cancelled.

onPressChange ?(pressed: boolean) => void

Called each time the “press” state changes.

onPressStart ?(event: PointerEvent) => void

Called when pointerdown occurs on the target.

onPressEnd ?(event: PointerEvent) => void

Called when pointerup occurs for a pointer that started on the target.

touchAction ?string

Sets how an element’s region can be manipulated by a touch pointer interaction. By explicitly specifying which gestures should be handled by the platform, an application can supply its own behavior for the remaining gestures. After a gesture starts, changes to touchAction will not have any impact on the behavior of the current gesture. Equivalent to CSS touch-action.


Examples #

Use onPressChange as a convenient way to listen to changes in the press state.

import usePress from 'react-gui/use-press';

function usePressState() {
const [pressed, onPressChange] = React.useState(false);
const ref = usePress({ onPressChange });
return [ref, pressed];
}
Updated
Edit
React GUICopyright © Facebook Inc.