# React Native Gesture Handler — Native Touch and Gesture System

> A gesture recognition library for React Native that replaces the JS-based touch system with native gesture recognizers, providing smooth pan, pinch, rotation, tap, and long-press handling that runs on the UI thread.

## Install

Save in your project root:

# React Native Gesture Handler — Native Touch and Gesture System

## Quick Use
```bash
npm install react-native-gesture-handler
npx pod-install
```
```jsx
import { GestureDetector, Gesture } from 'react-native-gesture-handler';
const pan = Gesture.Pan().onUpdate((e) => { console.log(e.translationX, e.translationY); });
<GestureDetector gesture={pan}>
  <View style={{ width: 100, height: 100, backgroundColor: 'coral' }} />
</GestureDetector>
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-7ca45194
Author: AI Open Source