/mobile-animation-gesture-handler

name: mobile-animation-gesture-handler
description: React Native Gesture Handler - gesture types, GestureDetector, gesture composition, state machine, platform-specific gestures, swipeable rows, hover gestures

React Native Gesture Handler Patterns

> **Quick Guide:** Use Gesture Handler's v2 builder API (`Gesture.Pan()`, `Gesture.Tap()`, etc.) with `GestureDetector` for all touch interactions. Wrap your app root in `GestureHandlerRootView`. Compose gestures with `Gesture.Simultaneous()`, `Gesture.Race()`, and `Gesture.Exclusive()`. Use `onChange` (not `onUpdate`) when working with animation shared values -- `onChange` provides deltas (`changeX`), `onUpdate` provides cumulative values (`translationX`). Gesture callbacks are automatically workletized when your animation library is installed.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST wrap the app root in `GestureHandlerRootView` -- gestures will silently fail without it)**

**(You MUST use `GestureDetector` with the builder API (`Gesture.Pan()`, etc.) -- NOT the legacy `PanGestureHandler` components)**

**(You MUST use `onChange` for incremental shared value updates and `onUpdate` for cumulative values -- mixing them causes drift)**

**(You MUST use `Gesture.Simultaneous()` for multi-touch interactions (pinch + pan) -- without it, only one gesture activates)**

**(You MUST NOT nest `GestureDetector` components using different API styles (hooks vs builder) under the same root -- this causes undefined behavior)**

</critical_requirements>

---

**Auto-detection:** react-native-gesture-handler, GestureDetector, GestureHandlerRootView, Gesture.Pan, Gesture.Tap, Gesture.Pinch, Gesture.Rotation, Gesture.LongPress, Gesture.Fling, Gesture.Hover, Gesture.Simultaneous, Gesture.Race, Gesture.Exclusive, Swipeable, ReanimatedSwipeable, onBegin, onStart, onChange, onUpdate, onEnd, onFinalize

**When to use:**

• Adding pan, pinch, tap, rotation, long-press, fling, or hover gestures to React Native views
• Composing multiple gestures on the same view (pinch-to-zoom + drag)
• Building swipeable list rows with reveal actions
• Replacing React Native's built-in Gesture Responder System (PanResponder)
• Implementing gesture-driven animations with shared values
• Adding hover interactions for iPad trackpad, desktop, or web targets

**Key patterns covered:**

• GestureDetector + builder API for all gesture types
• Gesture composition: Simultaneous, Race, Exclusive
• Gesture state machine and lifecycle callbacks
• Shared value integration in gesture callbacks (onChange vs onUpdate)
• ReanimatedSwipeable for swipeable list rows
• Hover gesture for pointer devices (iPad trackpad, mouse, stylus)
• Platform-specific gesture configuration (Android ripple, iOS haptics)
• Cross-component gesture relations (requireToFail, simultaneousWith, block)

**When NOT to use:**

• Simple button taps (use `Pressable` or `TouchableOpacity` from React Native core)
• Scroll-only interactions (use `ScrollView` or `FlatList` directly)
• Web-only applications without React Native

**Detailed Resources:**

• [examples/core.md](examples/core.md) - GestureDetector setup, pan, tap, pinch, rotation gestures with shared values
• [examples/composition.md](examples/composition.md) - Simultaneous, Race, Exclusive composition, cross-component relations
• [examples/swipeable.md](examples/swipeable.md) - ReanimatedSwipeable rows, FlatList integration, action panels
• [examples/advanced.md](examples/advanced.md) - Hover gesture, manual gesture control, platform-specific config
• [reference.md](reference.md) - Decision frameworks, gesture type reference, state machine diagram

---

<philosophy>

Philosophy

React Native Gesture Handler replaces the built-in Gesture Responder System with native-driven gesture recognition. The key advantage is that gestures are processed on the native thread, not JS -- so they remain responsive even when JS is busy.

**Core principles:**

1. **Native-first** -- Gesture recognition runs natively; callbacks optionally run as worklets on the UI thread 2. **Declarative composition** -- Define gestures as objects, compose them with `Simultaneous`, `Race`, `Exclusive` 3. **State machine driven** -- Every gesture follows UNDETERMINED -> BEGAN -> ACTIVE -> END/FAILED/CANCELLED 4. **Builder API** -- Chain configuration methods: `Gesture.Pan().minDistance(10).onUpdate(handler)` 5. **One GestureDetector per gesture (or composed gesture)** -- Don't attach multiple unrelated gestures via separate nested detectors

**Mental model:** Think of each gesture as a state machine that competes with other gestures for activation. Composition methods (`Simultaneous`, `Race`, `Exclusive`) define the competition rules. The gesture that wins transitions to ACTIVE; the rest FAIL or get CANCELLED.

**v3 hooks API (beta):** RNGH v3 introduces a hooks-based API (`usePanGesture`, `useSimultaneousGestures`, etc.) that is cleaner but still in beta. The v2 builder API (`Gesture.Pan()`, `GestureDetector`) is the stable production API documented here.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: GestureHandlerRootView Setup

Every app using Gesture Handler must wrap its root in `GestureHandlerRootView`. Without it, gestures silently fail -- no errors, just no recognition.

import { GestureHandlerRootView } from "react-native-gesture-handler";

export function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <AppContent />
    </GestureHandlerRootView>
  );
}

**Why good:** single root wrapper, `flex: 1` ensures full-screen coverage

**Gotcha (Android modals):** React Native Modals on Android create a separate native view hierarchy. Wrap Modal content in its own `GestureHandlerRootView` -- gestures inside a Modal won't work otherwise.

**Gotcha (native navigation):** When using a native navigation library (separate screen containers per screen), wrap each registered screen individually rath