React Native Gesture Handler — Native Touch and Gesture System

Introduction

React Native Gesture Handler replaces React Native's built-in touch responder system with platform-native gesture recognizers. By running gesture recognition on the UI thread, it eliminates the latency of JS-thread touch processing and enables fluid interactions like swipe-to-dismiss, pinch-to-zoom, and drag-to-reorder.

What React Native Gesture Handler Does

• Provides native Pan, Pinch, Rotation, Tap, LongPress, and Fling gesture recognizers
• Runs gesture recognition on the UI thread for zero-latency touch response
• Supports gesture composition: simultaneous, exclusive, and sequential gesture relationships
• Integrates with Reanimated for gesture-driven animations without JS thread involvement
• Handles nested scrollable views and gesture conflicts automatically

Architecture Overview

The library registers native gesture recognizers (UIGestureRecognizer on iOS, GestureDetector on Android) on the native view hierarchy. A gesture state machine manages transitions between states (UNDETERMINED, BEGAN, ACTIVE, END, CANCELLED, FAILED). When composed gestures conflict, the native layer resolves priority using requireFailureOf and simultaneousWithGesture relationships, avoiding JS-thread round trips.

Self-Hosting & Configuration

• Wrap the root component in GestureHandlerRootView for gesture event dispatch
• Use the Gesture API (v2) for composable gesture definitions
• Configure minPointers, maxPointers, minDist, and minVelocity for gesture thresholds
• Apply hitSlop to extend touchable areas beyond visible bounds
• Set enabled dynamically to activate or deactivate gestures based on app state

Key Features

• UI-thread gesture processing eliminates the 16ms+ latency of JS touch handling
• Gesture composition with Gesture.Simultaneous(), Gesture.Exclusive(), and Gesture.Race()
• Swipeable and DrawerLayout components for common swipe-based UI patterns
• Manual gesture for custom low-level touch event handling
• Native-driven velocity tracking for momentum-based fling detection

Comparison with Similar Tools

• PanResponder (built-in) — JS-thread gesture handling; Gesture Handler runs natively for lower latency
• react-native-draggable — drag-specific; Gesture Handler is a general-purpose gesture system
• Touchable components — tap-only handlers; Gesture Handler supports pan, pinch, rotation, and more
• Native UIGestureRecognizer — same underlying API; Gesture Handler wraps it in a React-friendly interface

FAQ

Q: Do I need GestureHandlerRootView? A: Yes. Wrap your app root in GestureHandlerRootView so the library can intercept touch events at the native level.

Q: How does it work with Reanimated? A: Gesture callbacks can directly update Reanimated shared values on the UI thread, enabling zero-latency gesture-to-animation pipelines.

Q: Can I combine multiple gestures? A: Yes. Use Gesture.Simultaneous() for gestures that should recognize together, or Gesture.Exclusive() for priority-based resolution.

Q: Is the old API (PanGestureHandler components) still supported? A: Yes, but the newer Gesture API (v2) is recommended for new code. Both APIs work side by side.

Sources

• https://github.com/software-mansion/react-native-gesture-handler
• https://docs.swmansion.com/react-native-gesture-handler/