usePan

Respond to pointer “pan” events on the element.

Provides an accessible way to listen to panning pointer interactions that can be used to implement specific gestures such as “swipe”, “pinch”, “rotate”, etc. It is not accessible to keyboards. This hook is implemented upon the Gestue Responder System provided by useResponder.

Each callback provided by usePan receives both the underlying ResponderEvent as well as the current PanState, which provides information about the current state of the gesture and the calculated centroid of pointers.

import { usePan } from 'react-gui/use-pan';

const ref = usePan(panProps);

API #

Return value #

usePan returns a React callback ref.

ref (?HTMLElement) => void

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

PanProps #

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.

Negotiation methods

onStartSetPan ?(event: ResponderEvent, state: PanState) => boolean

On pointerdown, should this view attempt to become the responder? If the view is not the responder, this method may be called for every pointer start on the view.

onStartSetPanCapture ?(event: ResponderEvent, state: PanState) => boolean

On pointerdown, should this view attempt to become the responder during the capture phase? If the view is not the responder, this method may be called for every pointer start on the view.

onMoveSetPan ?(event: ResponderEvent, state: PanState) => boolean

On pointermove for an active pointer, should this view attempt to become the responder? If the view is not the responder, this method may be called for every pointer move on the view.

onMoveSetPanCapture ?(event: ResponderEvent, state: PanState) => boolean

On pointermove for an active pointer, should this view attempt to become the responder during the capture phase? If the view is not the responder, this method may be called for every pointer move on the view.

onPanTerminationRequest ?(event: ResponderEvent, state: PanState) => boolean

The view is the responder, but another view now wants to become the responder. Should this view release the responder? Returning true allows the responder to be released.

Transfer methods

onPanGrant ?(event: ResponderEvent, state: PanState) => void

The view is granted the responder and is now responding to pointer events. The lifecycle methods will be called for this view. This is the point at which you should provide visual feedback for users that the interaction has begun.

onPanReject ?(event: ResponderEvent, state: PanState) => void

The view was not granted the responder. It was rejected because another view is already the responder and will not release it.

onPanTerminate ?(event: ResponderEvent, state: PanState) => void

The responder has been taken from this view. It may have been taken by another view after a call to onResponderTerminationRequest, or it might have been taken by the browser without asking (e.g., window blur, document scroll, context menu open). This is the point at which you should provide visual feedback for users that the interaction has been cancelled.

Lifecycle methods

onPanStart ?(event: ResponderEvent, state: PanState) => void

A pointer down event occured on the screen. The responder is notified of all start events, even if the pointer target is not this view (i.e., additional pointers are being used). Therefore, this method may be called multiple times while the view is the responder.

onPanMove ?(event: ResponderEvent, state: PanState) => void

A pointer move event occured on the screen. The responder is notified of all move events, even if the pointer target is not this view (i.e., additional pointers are being used). Therefore, this method may be called multiple times while the view is the responder.

onPanEnd ?(event: ResponderEvent, state: PanState) => void

A pointer up event occured on the screen. The responder is notified of all end events, even if the pointer target is not this view (i.e., additional pointers are being used). Therefore, this method may be called multiple times while the view is the responder.

onPanRelease ?(event: ResponderEvent, state: PanState) => void

As soon as there are no more pointers that started inside descendants of the responder, this method is called on the responder and the interaction lock is released. This is the point at which you should provide visual feedback for users that the interaction is over.

PanState #

Every method is called not only with the ResponderEvent but with a PanState object.

deltaX number

Accumulated horizontal distance the gesture has moved since the gesture started.

deltaY number

Accumulated vertical distance the gesture has moved since the gesture started.

gestureID number

The ID of the gesture; persisted as long as there is at least one active pointer on the screen.

initialX number

The initial horizontal screen coordinate of the gesture centroid.

initialY number

The initial vertical screen coordinate of the gesture centroid.

numberActiveTouches number

The number of pointers currently on the screen.

velocityX number

The current horizontal velocity of the gesture centroid.

velocityY number

The current vertical velocity of the gesture centroid.

x number

The lastest horizontal screen coordinate of the gesture centroid.

y number

The lastest vertical screen coordinate of the gesture centroid.


Examples #

import usePan from 'react-gui/use-pan';

function Component() {
const ref = usePan({
onStartSetPan,
onStartSetPanCapture,
onMoveSetPan(e, gestureState) {
// start gesture once centroid of pointers has moved horizontally
if (gestureState.deltaX > 10) {
return true;
}
},
onMoveSetPanCapture,
onPanGrant,
onPanStart,
onPanMove,
onPanEnd,
onPanRelease,
onPanTerminate,
onPanTerminationRequest
});

return <div ref={ref} />
}
Updated
Edit
React GUICopyright © Facebook Inc.