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.
A callback ref that must be passed to the target element.
PanProps #
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
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.
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.
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.
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.
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
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.
The view was not granted the responder. It was rejected because another view is already the responder and will not release it.
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
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.
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.
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.
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.
Accumulated horizontal distance the gesture has moved since the gesture started.
Accumulated vertical distance the gesture has moved since the gesture started.
The ID of the gesture; persisted as long as there is at least one active pointer on the screen.
The initial horizontal screen coordinate of the gesture centroid.
The initial vertical screen coordinate of the gesture centroid.
The number of pointers currently on the screen.
The current horizontal velocity of the gesture centroid.
The current vertical velocity of the gesture centroid.
The lastest horizontal screen coordinate of the gesture centroid.
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} />
}