Gesture callbacks & events

At any given time, each handler instance has an assigned state that can change when new touch events occur or can be forced to change by the touch system under certain circumstances. You can hook into state transitions using specific gesture callbacks.

When Reanimated is installed, all callbacks are automatically workletized. For more details, refer to the Integration with Reanimated section.

Callbacks flow

GestureEvent callbacks

Note that some of these callbacks are complementary:

• if onBegin was called, it is guaranteed that onFinalize will be called later.
• if onActivate was called, it is guaranteed that onDeactivate will be called later.

TouchEvent callbacks

Callbacks

onBegin

onBegin: (event: GestureEvent<HandlerData>) => void

Called when a handler begins to recognize gestures. If onBegin was called, it is guaranteed that onFinalize will be called later.

onActivate

onActivate: (event: GestureEvent<HandlerData>) => void

Called when activation criteria for the handler are met. If onActivate was called, it is guaranteed that onDeactivate will be called later.

onUpdate

onUpdate: (event: GestureEvent<HandlerData>) => void

Called each time a pointer tracked by the gesture changes state, typically due to movement, after the gesture has been activated.

onDeactivate

onDeactivate: (event: GestureEndEvent<HandlerData>) => void

Called when handler stops recognizing gestures, but only if the handler activated. It is called before onFinalize. The event object contains a canceled property — if the gesture was interrupted, canceled is set to true. Otherwise it is set to false.

onFinalize

onFinalize: (event: GestureEndEvent<HandlerData>) => void

Called when handler stops recognizing gestures. The event object contains a canceled property — if the handler failed to activate or was interrupted, canceled is set to true. If the handler managed to activate and completed successfully, canceled is set to false and onFinalize will be called right after onDeactivate.

onTouchesDown

onTouchesDown: (event: GestureTouchEvent) => void

Called when new pointers are placed on the screen. It may carry information about more than one pointer because the events are batched.

onTouchesMove

onTouchesMove: (event: GestureTouchEvent) => void

Called when pointers are moved on the screen. It may carry information about more than one pointer because the events are batched.

onTouchesUp

onTouchesUp: (event: GestureTouchEvent) => void

Called when pointers are lifted from the screen. It may carry information about more than one pointer because the events are batched.

onTouchesCancel

onTouchesCancel: (event: GestureTouchEvent) => void

Called when there will be no more information about this pointer. It may be called because the gesture has ended or was interrupted. It may carry information about more than one pointer because the events are batched.

Events

GestureEvent

export type GestureEvent<HandlerData> = {
handlerTag: number;
numberOfPointers: number;
pointerType: PointerType;
} & HandlerData;

export type GestureEndEvent<HandlerData> = {
canceled: boolean;

GestureEvent contains properties common to all gestures (handlerTag, numberOfPointers, pointerType) along with gesture-specific data defined in each gesture's documentation.

GestureEndEvent

GestureEndEvent extends GestureEvent with a canceled property. It is used in the onDeactivate and onFinalize callbacks. When canceled is true, the gesture was interrupted or failed to activate. When false, the gesture completed successfully.

TouchEvent

export type GestureTouchEvent = {
handlerTag: number;
numberOfTouches: number;
state: State;
eventType: TouchEventType;
allTouches: TouchData[];
changedTouches: TouchData[];
pointerType: PointerType;

TouchEvent carries information about raw touch events, like touching the screen or moving the finger.

• eventType - Type of the current event - whether the finger was placed on the screen, moved, lifted or cancelled.

• changedTouches - An array of objects where every object represents a single touch. Contains information only about the touches that were affected by the event i.e. those that were placed down, moved, lifted or cancelled.

• allTouches - An array of objects where every object represents a single touch. Contains information about all active touches.

• numberOfTouches - Number representing the count of currently active touches.

TouchData contains information about a single touch.

• id - A number representing the id of the touch. It may be used to track the touch between events as the id will not change while it is being tracked.

• x - X coordinate of the current position of the touch relative to the view attached to the GestureDetector. Expressed in point units.

• y - Y coordinate of the current position of the touch relative to the view attached to the GestureDetector. Expressed in point units.

• absoluteX - X coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of x in cases when the original view can be transformed as an effect of the gesture.

• absoluteY - Y coordinate of the current position of the touch relative to the window. The value is expressed in point units. It is recommended to use it instead of y in cases when the original view can be transformed as an effect of the gesture.

danger

Don't rely on the order of items in the changedTouches/allTouches arrays as it may change during the gesture, instead use the id attribute to track individual touches across events.