The React Native Gesture Handler State Machine

Why it exists

Simple event listeners don't capture the full lifecycle of a continuous gesture like dragging or pinching. To build fluid, interruptible interactions, you need more than a single 'tap' event; you need to know when a gesture starts, is active, and ends or gets cancelled.

The mental model

A gesture handler is a state machine. At any moment, it's in one of six states: UNDETERMINED, BEGAN, ACTIVE, END, FAILED, or CANCELLED. Your code doesn't just react to a gesture; it reacts to the handler's transition between these states as it processes touch events over time.

How it works

Every handler starts in the UNDETERMINED state. On first touch, it moves to BEGAN. If it receives enough touch data to recognize its gesture (e.g., a long press duration is met), it becomes ACTIVE. It stays ACTIVE as long as the gesture continues. When the user finishes (e.g., lifts their finger), it moves to END, then resets to UNDETERMINED. If the gesture is interrupted by the system, it moves from ACTIVE to CANCELLED. If the initial touches don't match the gesture's rules, it moves from BEGAN to FAILED. You monitor these changes using the onHandlerStateChange callback.

When to use it

Use the state machine model for any continuous gesture (pans, pinches, rotations) or complex interaction. This allows you to manage UI that changes during the gesture itself, like highlighting a button when a press BEGANs, dragging an element while the gesture is ACTIVE, and snapping it to a final position on END.

When not to use it

For the simplest discrete actions, like a basic button tap that only triggers one action, you might not need to manually inspect every state. The library often provides simpler callbacks for these cases, but the state machine is always operating underneath.

One canonical example

Consider a draggable card. When its pan gesture state becomes ACTIVE, you start updating the card's position from the event's translation values. While it remains ACTIVE, you continue updating its position on every frame. When the state becomes END, you might run a 'snap-back' animation. Crucially, if a parent ScrollView takes over and the state becomes CANCELLED, you must reset the card to its original position to avoid it getting stuck mid-drag.