0
# Gesture Event System
1

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

4
## Capabilities
5

6
### Core Event Types
7

8
Base event types used throughout the gesture handling system.
9

10
```typescript { .api }
11
/**
12
 * Basic gesture event structure
13
 * Contains native event data with handler and state information
14
 */
15
interface GestureEvent<T = Record<string, unknown>> {
16
  nativeEvent: T & {
17
    handlerTag: number;
18
    numberOfPointers: number;
19
    state: number;
20
  };
21
}
22

23
/**
24
 * Handler state change event structure
25
 * Fired when gesture handler changes state (begin, active, end, etc.)
26
 */
27
interface HandlerStateChangeEvent<T = Record<string, unknown>> {
28
  nativeEvent: T & {
29
    handlerTag: number;
30
    numberOfPointers: number;
31
    state: number;
32
    oldState: number;
33
  };
34
}
35
```
36

37
### Modern API Event Types
38

39
Event types used with the new Gesture API (`GestureDetector` and `Gesture` factory).
40

41
```typescript { .api }
42
/**
43
 * Update event for the modern Gesture API
44
 * Provides real-time gesture data during interaction
45
 */
46
interface GestureUpdateEvent<T = Record<string, unknown>> {
47
  x: number;
48
  y: number;
49
  absoluteX: number;
50
  absoluteY: number;
51
  handlerTag: number;
52
  numberOfPointers: number;
53
  state: number;
54
} & T;
55

56
/**
57
 * State change event for the modern Gesture API
58
 * Fired when gesture state transitions occur
59
 */
60
interface GestureStateChangeEvent<T = Record<string, unknown>> {
61
  x: number;
62
  y: number;
63
  absoluteX: number;
64
  absoluteY: number;
65
  handlerTag: number;
66
  numberOfPointers: number;
67
  state: number;
68
  oldState: number;
69
} & T;
70
```
71

72
### Touch Event Types
73

74
Advanced touch event types providing detailed touch information.
75

76
```typescript { .api }
77
/**
78
 * Touch event with multiple pointer support
79
 * Contains detailed information about all active touches
80
 */
81
interface GestureTouchEvent {
82
  handlerTag: number;
83
  numberOfTouches: number;
84
  state: number;
85
  eventType: number;
86
  allTouches: TouchData[];
87
  changedTouches: TouchData[];
88
}
89

90
/**
91
 * Individual touch data
92
 * Detailed information about a single touch point
93
 */
94
interface TouchData {
95
  id: number;
96
  x: number;
97
  y: number;
98
  absoluteX: number;
99
  absoluteY: number;
100
  force?: number;
101
  timestamp: number;
102
}
103
```
104

105
## Gesture-Specific Event Payloads
106

107
### Tap Gesture Events
108

109
Events specific to tap gesture interactions.
110

111
```typescript { .api }
112
/**
113
 * Tap gesture event payload
114
 * Contains position information for tap gestures
115
 */
116
interface TapGestureHandlerEventPayload {
117
  x: number;
118
  y: number;
119
  absoluteX: number;
120
  absoluteY: number;
121
}
122

123
// Complete tap gesture event types
124
type TapGestureHandlerGestureEvent = GestureEvent<TapGestureHandlerEventPayload>;
125
type TapGestureHandlerStateChangeEvent = HandlerStateChangeEvent<TapGestureHandlerEventPayload>;
126
```
127

128
### Pan Gesture Events
129

130
Events specific to pan/drag gesture interactions.
131

132
```typescript { .api }
133
/**
134
 * Pan gesture event payload
135
 * Contains position, translation, and velocity information
136
 */
137
interface PanGestureHandlerEventPayload {
138
  x: number;
139
  y: number;
140
  absoluteX: number;
141
  absoluteY: number;
142
  translationX: number;
143
  translationY: number;
144
  velocityX: number;
145
  velocityY: number;
146
  stylusData?: StylusData;
147
}
148

149
/**
150
 * Pan gesture change event payload (New API)
151
 * Streamlined payload for modern pan gestures
152
 */
153
interface PanGestureChangeEventPayload {
154
  translationX: number;
155
  translationY: number;
156
  velocityX: number;
157
  velocityY: number;
158
}
159

160
/**
161
 * Stylus-specific data for supported devices
162
 */
163
interface StylusData {
164
  pressure: number;
165
  tiltX: number;
166
  tiltY: number;
167
  twist: number;
168
}
169

170
// Complete pan gesture event types
171
type PanGestureHandlerGestureEvent = GestureEvent<PanGestureHandlerEventPayload>;
172
type PanGestureHandlerStateChangeEvent = HandlerStateChangeEvent<PanGestureHandlerEventPayload>;
173
```
174

175
### Pinch Gesture Events
176

177
Events specific to pinch/zoom gesture interactions.
178

179
```typescript { .api }
180
/**
181
 * Pinch gesture event payload
182
 * Contains scale factor and focal point information
183
 */
184
interface PinchGestureHandlerEventPayload {
185
  x: number;
186
  y: number;
187
  absoluteX: number;
188
  absoluteY: number;
189
  scale: number;
190
  focalX: number;
191
  focalY: number;
192
  velocity: number;
193
}
194

195
/**
196
 * Pinch gesture change event payload (New API)
197
 * Streamlined payload for modern pinch gestures
198
 */
199
interface PinchGestureChangeEventPayload {
200
  scale: number;
201
  focalX: number;
202
  focalY: number;
203
  velocity: number;
204
}
205

206
// Complete pinch gesture event types
207
type PinchGestureHandlerGestureEvent = GestureEvent<PinchGestureHandlerEventPayload>;
208
type PinchGestureHandlerStateChangeEvent = HandlerStateChangeEvent<PinchGestureHandlerEventPayload>;
209
```
210

211
### Rotation Gesture Events
212

213
Events specific to rotation gesture interactions.
214

215
```typescript { .api }
216
/**
217
 * Rotation gesture event payload
218
 * Contains rotation angle and anchor point information
219
 */
220
interface RotationGestureHandlerEventPayload {
221
  x: number;
222
  y: number;
223
  absoluteX: number;
224
  absoluteY: number;
225
  rotation: number; // in radians
226
  anchorX: number;
227
  anchorY: number;
228
  velocity: number;
229
}
230

231
// Complete rotation gesture event types
232
type RotationGestureHandlerGestureEvent = GestureEvent<RotationGestureHandlerEventPayload>;
233
type RotationGestureHandlerStateChangeEvent = HandlerStateChangeEvent<RotationGestureHandlerEventPayload>;
234
```
235

236
### Long Press Gesture Events
237

238
Events specific to long press gesture interactions.
239

240
```typescript { .api }
241
/**
242
 * Long press gesture event payload
243
 * Contains position and duration information
244
 */
245
interface LongPressGestureHandlerEventPayload {
246
  x: number;
247
  y: number;
248
  absoluteX: number;
249
  absoluteY: number;
250
  duration: number; // in milliseconds
251
}
252

253
// Complete long press gesture event types
254
type LongPressGestureHandlerGestureEvent = GestureEvent<LongPressGestureHandlerEventPayload>;
255
type LongPressGestureHandlerStateChangeEvent = HandlerStateChangeEvent<LongPressGestureHandlerEventPayload>;
256
```
257

258
### Fling Gesture Events
259

260
Events specific to fling/swipe gesture interactions.
261

262
```typescript { .api }
263
/**
264
 * Fling gesture event payload
265
 * Contains position information for fling gestures
266
 */
267
interface FlingGestureHandlerEventPayload {
268
  x: number;
269
  y: number;
270
  absoluteX: number;
271
  absoluteY: number;
272
}
273

274
// Complete fling gesture event types
275
type FlingGestureHandlerGestureEvent = GestureEvent<FlingGestureHandlerEventPayload>;
276
type FlingGestureHandlerStateChangeEvent = HandlerStateChangeEvent<FlingGestureHandlerEventPayload>;
277
```
278

279
### Force Touch Gesture Events (Deprecated)
280

281
Events specific to force touch gesture interactions (deprecated feature).
282

283
```typescript { .api }
284
/**
285
 * Force touch gesture event payload (deprecated)
286
 * Contains position and force information
287
 * @deprecated Force touch is deprecated
288
 */
289
interface ForceTouchGestureHandlerEventPayload {
290
  x: number;
291
  y: number;
292
  absoluteX: number;
293
  absoluteY: number;
294
  force: number; // 0.0 to 1.0
295
}
296

297
/**
298
 * Force touch gesture change event payload (New API, deprecated)
299
 * @deprecated Force touch is deprecated
300
 */
301
interface ForceTouchGestureChangeEventPayload {
302
  force: number;
303
}
304

305
// Complete force touch gesture event types
306
type ForceTouchGestureHandlerGestureEvent = GestureEvent<ForceTouchGestureHandlerEventPayload>;
307
type ForceTouchGestureHandlerStateChangeEvent = HandlerStateChangeEvent<ForceTouchGestureHandlerEventPayload>;
308
```
309

310
### Native View Gesture Events
311

312
Events specific to native view gesture interactions.
313

314
```typescript { .api }
315
/**
316
 * Native view gesture event payload
317
 * Contains pointer inside/outside information
318
 */
319
interface NativeViewGestureHandlerPayload {
320
  pointerInside: boolean;
321
}
322

323
// Complete native view gesture event types
324
type NativeViewGestureHandlerGestureEvent = GestureEvent<NativeViewGestureHandlerPayload>;
325
type NativeViewGestureHandlerStateChangeEvent = HandlerStateChangeEvent<NativeViewGestureHandlerPayload>;
326
```
327

328
## Event Usage Examples
329

330
### Basic Event Handling
331

332
```typescript
333
import React from "react";
334
import { View, Text } from "react-native";
335
import { GestureDetector, Gesture } from "react-native-gesture-handler";
336

337
function EventHandlingExample() {
338
  const tapGesture = Gesture.Tap()
339
    .onBegin((event) => {
340
      console.log("Tap began at:", event.x, event.y);
341
    })
342
    .onStart((event) => {
343
      console.log("Tap started at:", event.absoluteX, event.absoluteY);
344
    })
345
    .onEnd((event) => {
346
      console.log("Tap ended with state:", event.state);
347
    });
348

349
  const panGesture = Gesture.Pan()
350
    .onUpdate((event) => {
351
      console.log("Pan translation:", event.translationX, event.translationY);
352
      console.log("Pan velocity:", event.velocityX, event.velocityY);
353
    })
354
    .onEnd((event) => {
355
      console.log("Pan ended with final translation:", event.translationX, event.translationY);
356
    });
357

358
  return (
359
    <GestureDetector gesture={Gesture.Simultaneous(tapGesture, panGesture)}>
360
      <View style={{ width: 200, height: 200, backgroundColor: "lightblue" }}>
361
        <Text>Tap and Pan Events</Text>
362
      </View>
363
    </GestureDetector>
364
  );
365
}
366
```
367

368
### Advanced Event Processing
369

370
```typescript
371
import React, { useCallback } from "react";
372
import { View } from "react-native";
373
import { GestureDetector, Gesture } from "react-native-gesture-handler";
374

375
function AdvancedEventProcessing() {
376
  const handlePinchUpdate = useCallback((event: GestureUpdateEvent<PinchGestureChangeEventPayload>) => {
377
    const { scale, focalX, focalY, velocity } = event;
378
    
379
    // Process pinch data
380
    console.log(`Pinch: scale=${scale.toFixed(2)}, focal=(${focalX.toFixed(0)}, ${focalY.toFixed(0)})`);
381
    
382
    // Apply scale with velocity damping
383
    const dampedScale = scale * (1 - velocity * 0.01);
384
    console.log(`Damped scale: ${dampedScale.toFixed(2)}`);
385
  }, []);
386

387
  const handleRotationUpdate = useCallback((event: GestureUpdateEvent<RotationGestureChangeEventPayload>) => {
388
    const { rotation, anchorX, anchorY, velocity } = event;
389
    
390
    // Convert radians to degrees
391
    const degrees = (rotation * 180) / Math.PI;
392
    console.log(`Rotation: ${degrees.toFixed(1)}°, anchor=(${anchorX.toFixed(0)}, ${anchorY.toFixed(0)})`);
393
  }, []);
394

395
  const pinchGesture = Gesture.Pinch().onUpdate(handlePinchUpdate);
396
  const rotationGesture = Gesture.Rotation().onUpdate(handleRotationUpdate);
397

398
  return (
399
    <GestureDetector gesture={Gesture.Simultaneous(pinchGesture, rotationGesture)}>
400
      <View style={{ width: 300, height: 300, backgroundColor: "lightgreen" }} />
401
    </GestureDetector>
402
  );
403
}
404
```
405

406
### Touch Event Processing
407

408
```typescript
409
import React from "react";
410
import { View } from "react-native";
411
import { GestureDetector, Gesture } from "react-native-gesture-handler";
412

413
function TouchEventProcessing() {
414
  const panGesture = Gesture.Pan()
415
    .onUpdate((event) => {
416
      // Access basic touch information
417
      console.log(`Touch at: (${event.x}, ${event.y})`);
418
      console.log(`Absolute position: (${event.absoluteX}, ${event.absoluteY})`);
419
      console.log(`Number of pointers: ${event.numberOfPointers}`);
420
      
421
      // Pan-specific data
422
      if ('translationX' in event && 'translationY' in event) {
423
        console.log(`Translation: (${event.translationX}, ${event.translationY})`);
424
        console.log(`Velocity: (${event.velocityX}, ${event.velocityY})`);
425
      }
426
    });
427

428
  return (
429
    <GestureDetector gesture={panGesture}>
430
      <View style={{ width: 200, height: 200, backgroundColor: "orange" }} />
431
    </GestureDetector>
432
  );
433
}
434
```
435

436
## Event State Management
437

438
### Gesture States
439

440
Understanding gesture states is crucial for proper event handling:
441

442
```typescript
443
import { State } from "react-native-gesture-handler";
444

445
function handleStateChange(event: GestureStateChangeEvent) {
446
  switch (event.state) {
447
    case State.UNDETERMINED:
448
      console.log("Gesture state: UNDETERMINED");
449
      break;
450
    case State.FAILED:
451
      console.log("Gesture state: FAILED");
452
      break;
453
    case State.BEGAN:
454
      console.log("Gesture state: BEGAN");
455
      break;
456
    case State.CANCELLED:
457
      console.log("Gesture state: CANCELLED");
458
      break;
459
    case State.ACTIVE:
460
      console.log("Gesture state: ACTIVE");
461
      break;
462
    case State.END:
463
      console.log("Gesture state: END");
464
      break;
465
  }
466
}
467
```
468

469
### Event Timing
470

471
Events provide timing information for performance analysis:
472

473
```typescript
474
function analyzeEventTiming(event: GestureUpdateEvent) {
475
  // Most events include timestamp information
476
  const timestamp = Date.now();
477
  console.log(`Event processed at: ${timestamp}`);
478
  
479
  // For long press gestures, duration is available
480
  if ('duration' in event) {
481
    console.log(`Long press duration: ${event.duration}ms`);
482
  }
483
}
484
```
485

486
## Performance Considerations
487

488
### Event Frequency
489

490
Gesture update events fire frequently. Optimize handlers for performance:
491

492
```typescript
493
import { runOnUI } from "react-native-reanimated";
494

495
// ✅ Good: Use runOnUI for performance-critical calculations
496
const panGesture = Gesture.Pan().onUpdate((event) => {
497
  'worklet';
498
  runOnUI(() => {
499
    // Perform calculations on UI thread
500
    const distance = Math.sqrt(event.translationX ** 2 + event.translationY ** 2);
501
    console.log(`Distance: ${distance}`);
502
  })();
503
});
504

505
// ❌ Avoid: Heavy calculations on JavaScript thread
506
const badPanGesture = Gesture.Pan().onUpdate((event) => {
507
  // Heavy calculation on JS thread - will cause stuttering
508
  const expensiveCalculation = performComplexMath(event);
509
});
510
```
511

512
### Memory Management
513

514
Properly clean up event handlers to prevent memory leaks:
515

516
```typescript
517
import React, { useEffect, useCallback } from "react";
518

519
function MemoryEfficientEvents() {
520
  const handleUpdate = useCallback((event) => {
521
    // Event handling logic
522
  }, []);
523

524
  useEffect(() => {
525
    // Cleanup if needed
526
    return () => {
527
      // Clean up resources
528
    };
529
  }, []);
530

531
  const gesture = Gesture.Pan().onUpdate(handleUpdate);
532

533
  return (
534
    <GestureDetector gesture={gesture}>
535
      {/* Component content */}
536
    </GestureDetector>
537
  );
538
}
539
```