0
# React Native Gesture Handler
1

2
React Native Gesture Handler is a comprehensive native-driven gesture management system for React Native applications. It moves gesture recognition and tracking from JavaScript to the native UI thread, providing high-performance touch interactions, smooth animations, and cross-platform support for iOS, Android, and Web.
3

4
## Package Information
5

6
- **Package Name**: react-native-gesture-handler
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install react-native-gesture-handler`
10

11
## Core Imports
12

13
```typescript
14
import {
15
  GestureDetector,
16
  Gesture,
17
  GestureHandlerRootView,
18
} from "react-native-gesture-handler";
19
```
20

21
For CommonJS:
22

23
```javascript
24
const {
25
  GestureDetector,
26
  Gesture,
27
  GestureHandlerRootView,
28
} = require("react-native-gesture-handler");
29
```
30

31
## Basic Usage
32

33
```typescript
34
import React from "react";
35
import { View } from "react-native";
36
import {
37
  GestureDetector,
38
  Gesture,
39
  GestureHandlerRootView,
40
} from "react-native-gesture-handler";
41

42
export default function App() {
43
  const tapGesture = Gesture.Tap()
44
    .numberOfTaps(2)
45
    .onEnd(() => {
46
      console.log("Double tap detected!");
47
    });
48

49
  return (
50
    <GestureHandlerRootView style={{ flex: 1 }}>
51
      <GestureDetector gesture={tapGesture}>
52
        <View style={{ width: 100, height: 100, backgroundColor: "red" }} />
53
      </GestureDetector>
54
    </GestureHandlerRootView>
55
  );
56
}
57
```
58

59
## Architecture
60

61
React Native Gesture Handler provides two main APIs:
62

63
- **Modern Gesture API**: Recommended approach using `GestureDetector` and `Gesture` factory for creating composable, performant gestures
64
- **Legacy Handler Components**: Deprecated individual gesture handler components (TapGestureHandler, PanGestureHandler, etc.)
65
- **Enhanced Components**: Drop-in replacements for React Native components with gesture support
66
- **Native Thread Processing**: Gestures are processed on the native UI thread for maximum performance
67
- **Reanimated Integration**: Seamless integration with react-native-reanimated for smooth animations
68

69
## Capabilities
70

71
### Setup and Root Components
72

73
Essential components and setup required for gesture handlers to function properly in React Native applications.
74

75
```typescript { .api }
76
// Root component required for gestures to work
77
function GestureHandlerRootView(props: {
78
  style?: StyleProp<ViewStyle>;
79
  children?: React.ReactNode;
80
}): JSX.Element;
81

82
// Legacy HOC for wrapping app root (deprecated)
83
function gestureHandlerRootHOC<T>(
84
  Component: React.ComponentType<T>,
85
  containerStyles?: StyleProp<ViewStyle>
86
): React.ComponentType<T>;
87
```
88

89
[Setup and Root Components](./setup.md)
90

91
### Modern Gesture API
92

93
The recommended approach for creating sophisticated gesture interactions using the new Gesture API with `GestureDetector` and `Gesture` factory methods.
94

95
```typescript { .api }
96
// Main component for detecting gestures
97
function GestureDetector(props: {
98
  gesture: ComposedGesture | GestureType;
99
  userSelect?: UserSelect;
100
  enableContextMenu?: boolean;
101
  touchAction?: TouchAction;
102
  children?: React.ReactNode;
103
}): JSX.Element;
104

105
// Factory object for creating gestures
106
interface GestureObjects {
107
  Tap(): TapGestureType;
108
  Pan(): PanGestureType;
109
  Pinch(): PinchGestureType;
110
  Rotation(): RotationGestureType;
111
  Fling(): FlingGestureType;
112
  LongPress(): LongPressGestureType;
113
  ForceTouch(): ForceTouchGestureType; // Deprecated
114
  Native(): NativeGestureType;
115
  Manual(): ManualGestureType;
116
  Hover(): HoverGestureType;
117
  Race(...gestures: GestureType[]): RaceGestureType;
118
  Simultaneous(...gestures: GestureType[]): SimultaneousGestureType;
119
  Exclusive(...gestures: GestureType[]): ExclusiveGestureType;
120
}
121
```
122

123
[Modern Gesture API](./gestures.md)
124

125
### Button Components
126

127
High-performance button components with native feedback and gesture support for creating interactive UI elements.
128

129
```typescript { .api }
130
// Base button with gesture handling
131
function BaseButton(props: {
132
  onPress?: (pointerInside: boolean) => void;
133
  onLongPress?: () => void;
134
  onActiveStateChange?: (active: boolean) => void;
135
  delayLongPress?: number;
136
  children?: React.ReactNode;
137
}): JSX.Element;
138

139
// Rectangular button with underlay effect
140
function RectButton(props: BaseButtonProps & {
141
  underlayColor?: string;
142
  activeOpacity?: number;
143
}): JSX.Element;
144

145
// Borderless button with opacity effect
146
function BorderlessButton(props: BaseButtonProps & {
147
  activeOpacity?: number;
148
}): JSX.Element;
149
```
150

151
[Button Components](./buttons.md)
152

153
### Enhanced React Native Components
154

155
Drop-in replacements for standard React Native components with enhanced gesture support and performance optimizations.
156

157
```typescript { .api }
158
// Enhanced ScrollView with gesture handler support
159
function ScrollView(props: ScrollViewProps): JSX.Element;
160

161
// Enhanced FlatList with gesture handler support
162
function FlatList<T>(props: FlatListProps<T>): JSX.Element;
163

164
// Enhanced touchable components
165
function TouchableOpacity(props: TouchableOpacityProps): JSX.Element;
166
function TouchableHighlight(props: TouchableHighlightProps): JSX.Element;
167
function TouchableWithoutFeedback(props: TouchableWithoutFeedbackProps): JSX.Element;
168
```
169

170
[Enhanced Components](./components.md)
171

172
### Advanced Layout Components
173

174
Sophisticated layout and interaction components for complex UI patterns like swipe-to-reveal and drawer layouts.
175

176
```typescript { .api }
177
// Swipe-to-reveal component
178
function Swipeable(props: {
179
  friction?: number;
180
  leftThreshold?: number;
181
  rightThreshold?: number;
182
  renderLeftActions?: (
183
    progressAnimatedValue: Animated.AnimatedAddition,
184
    dragX: Animated.AnimatedAddition
185
  ) => React.ReactNode;
186
  renderRightActions?: (
187
    progressAnimatedValue: Animated.AnimatedAddition,
188
    dragX: Animated.AnimatedAddition
189
  ) => React.ReactNode;
190
  children: React.ReactNode;
191
}): JSX.Element;
192

193
// Modern pressable component
194
function Pressable(props: PressableProps & {
195
  simultaneousWithExternalGesture?: GestureRef[];
196
  requireExternalGestureToFail?: GestureRef[];
197
  blocksExternalGesture?: GestureRef[];
198
}): JSX.Element;
199
```
200

201
[Advanced Layout Components](./advanced-components.md)
202

203
### Gesture Event System
204

205
Comprehensive event types and payload structures for handling gesture interactions with detailed coordinate and timing information.
206

207
```typescript { .api }
208
// Core event types
209
interface GestureEvent<T = Record<string, unknown>> {
210
  nativeEvent: T & {
211
    handlerTag: number;
212
    numberOfPointers: number;
213
    state: number;
214
  };
215
}
216

217
interface HandlerStateChangeEvent<T = Record<string, unknown>> {
218
  nativeEvent: T & {
219
    handlerTag: number;
220
    numberOfPointers: number;
221
    state: number;
222
    oldState: number;
223
  };
224
}
225

226
// New API event types
227
interface GestureUpdateEvent<T = Record<string, unknown>> {
228
  x: number;
229
  y: number;
230
  absoluteX: number;
231
  absoluteY: number;
232
  handlerTag: number;
233
  numberOfPointers: number;
234
  state: number;
235
} & T;
236

237
interface GestureStateChangeEvent<T = Record<string, unknown>> {
238
  x: number;
239
  y: number;
240
  absoluteX: number;
241
  absoluteY: number;
242
  handlerTag: number;
243
  numberOfPointers: number;
244
  state: number;
245
  oldState: number;
246
} & T;
247
```
248

249
[Gesture Event System](./events.md)
250

251
### Constants and Enums
252

253
Essential constants for gesture states, directions, pointer types, and mouse button handling across all gesture interactions.
254

255
```typescript { .api }
256
// Gesture states
257
const State: {
258
  readonly UNDETERMINED: 0;
259
  readonly FAILED: 1;
260
  readonly BEGAN: 2;
261
  readonly CANCELLED: 3;
262
  readonly ACTIVE: 4;
263
  readonly END: 5;
264
};
265

266
// Direction constants
267
const Directions: {
268
  readonly RIGHT: 1;
269
  readonly LEFT: 2;
270
  readonly UP: 4;
271
  readonly DOWN: 8;
272
};
273

274
// Pointer input types
275
enum PointerType {
276
  TOUCH,
277
  STYLUS,
278
  MOUSE,
279
  KEY,
280
  OTHER,
281
}
282

283
// Mouse button constants
284
enum MouseButton {
285
  LEFT = 1,
286
  RIGHT = 2,
287
  MIDDLE = 4,
288
  BUTTON_4 = 8,
289
  BUTTON_5 = 16,
290
  ALL = 31,
291
}
292
```
293

294
[Constants and Enums](./constants.md)
295

296
## Migration Guide
297

298
React Native Gesture Handler provides both legacy and modern APIs. The legacy gesture handler components (TapGestureHandler, PanGestureHandler, etc.) are deprecated in favor of the new Gesture API. While legacy components still work, new projects should use the modern `GestureDetector` and `Gesture` factory approach for better performance and composability.
299

300
## Web Implementation
301

302
React Native Gesture Handler includes comprehensive web support with automatic platform-specific implementations. Web-specific configurations include:
303

304
- `userSelect` - Controls text selection behavior
305
- `enableContextMenu` - Enables/disables right-click context menu
306
- `touchAction` - CSS touch-action property for web interactions