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