Composing Gestures: Race, Simultaneous, Exclusive

WHY IT EXISTS: In the legacy React Native touch system, one view could claim exclusive ownership of an active touch, which made complex interactions like pinching an image inside a scrolling gallery nearly impossible because the scroll view would greedily capture the stream. Gesture composition was invented to let multiple detectors evaluate the same raw touch data without a single monolithic handler blocking everyone else.

THE MENTAL MODEL: Think of each gesture as an independent state machine watching the same touch stream. Instead of one component grabbing a lock and silencing the rest, a composer acts as a referee that decides which machines may activate, in what order, and whether they can run at the same time.

HOW IT WORKS: You build individual gestures with React Native Gesture Handler, then wrap them in a composer. Simultaneous lets multiple gestures activate together. Race allows the first gesture to meet its criteria to win and cancels the rest. Exclusive enforces priority order, which is essential when one gesture is a subset of another, such as a single tap waiting for a double tap to fail. The resulting composed gesture is passed to a single GestureDetector.

WHEN TO USE IT: Use composition whenever one view or overlapping views need more than one touch interpretation. Common scenarios include a photo viewer that pans, pinches, and double taps; a list item that scrolls vertically while accepting horizontal swipes; or a button that must distinguish between a tap and a long press.

WHEN NOT TO USE IT: Do not use it for elements that are already spatially separated, like a top banner and a bottom slider, because they already have independent touch responders. Also avoid composition when a single gesture with custom state logic can handle the interaction, since every added gesture increases negotiation overhead and can introduce subtle timing bugs.

ONE CANONICAL EXAMPLE: Consider a photo gallery where a ScrollView handles vertical paging and an inner image supports pinch to zoom and pan. Without Simultaneous, the ScrollView captures the two finger touch and the image never receives it. By composing the native scroll gesture with pinch and pan via Simultaneous, all three detectors evaluate the stream together. The pinch activates on two fingers while the scroll waits, and once the pinch ends the scroll resumes. Using Race here would be a footgun, because lifting one finger mid pinch could accidentally trigger a scroll.