Skip to main content
Version: 3.x

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 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: GestureEvent<HandlerData>, didSucceed: boolean) => void

Called after when handler stops recognizing gestures, but only if handler activated. It is called before onFinalize. If the handler was interrupted, the didSucceed argument is set to false. Otherwise it is set to true.

onFinalize​

onFinalize: (event: GestureEvent<HandlerData>, didSucceed: boolean) => void

Called when handler stops recognizing gestures. If handler managed to activate, the didSucceed argument is set to true and onFinalize will be called right after onDeactivate. Otherwise it is set to false.

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;

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

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 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.