Gesture Handler

Software Mansion’s library that recognizes gestures (pan, tap, pinch, and more) natively and composes them, with callbacks on the UI thread.

Updated October 26, 2026

Definition

React Native Gesture Handler is Software Mansion’s library for handling touch gestures natively in React Native. Instead of React Native’s JavaScript touch responder system (PanResponder), where every finger movement crosses the JS thread, it delegates recognition to the native recognizers of iOS and Android, then, since version 3, exposes a hook-based API: usePanGesture(), useTapGesture(), usePinchGesture(), useLongPressGesture(), attached to a view through GestureDetector. Gestures compose with useCompetingGestures, useSimultaneousGestures, and useExclusiveGestures to describe which one wins when several apply; these hooks replace v2’s Gesture.Pan() and Gesture.Race(). When Reanimated is installed, callbacks are automatically turned into worklets and run on the UI thread, which lets you track the finger on every frame without stutter. It is also a dependency of React Navigation (drawer, JavaScript stack). You meet it for a swipe-to-delete, a bottom sheet, a carousel, or an image zoom.

In a real app

The install requires a GestureHandlerRootView at the root of the app (the Expo template puts it there for you), otherwise gestures do not respond on Android, often with no message at all. The API to use today is the version 3 hooks (usePanGesture and friends) with GestureDetector; the v2 Gesture builder and the older PanGestureHandler components are no longer the recommended path. Callbacks (onBegin, onActivate, onUpdate, onDeactivate) follow the gesture state machine, and onUpdate fires on every frame.

The central pitfall is composition with scroll views and navigators: a horizontal Pan inside a vertical list, the native stack’s back gesture, a ScrollView swallowing the gesture. activation and failure offsets, simultaneousWith, and requireToFail are the settings to know, and it has to be tested on an Android device, whose touch dispatch differs from iOS. A gesture that works on the iOS simulator and not on Android is the textbook case.

With Reanimated, callbacks are worklets: no setState or navigation inside without scheduleOnRN. To confirm a gesture is handled natively, a console.log in onUpdate should come from the UI runtime, and smoothness should hold while a heavy setState runs on the JS thread.

Sources

All 35 glossary terms

In a real app

Related terms

Sources

One of these is blocking your app?