{"id":11774,"library":"react-native-gesture-handler","title":"React Native Gesture Handler","description":"React Native Gesture Handler is a declarative API that exposes the native platform's touch and gesture system to React Native applications. It provides a robust and performant way to handle complex gestures like pan, pinch, rotate, and tap directly on the native UI thread, leading to smoother animations and a more responsive user experience compared to JavaScript-based gesture systems. The current stable version is 2.31.1, with an active release cadence that frequently publishes patch and minor updates, and a significant version 3.0 in public beta. Key differentiators include its deep integration with the native UI, enabling seamless interoperability with `react-native-reanimated` for advanced animations, and its move towards a hook-based API in version 3 designed for React Native's New Architecture. It aims to reduce the load on the JavaScript thread by offloading gesture recognition to the native side.","status":"active","version":"2.31.1","language":"javascript","source_language":"en","source_url":"https://github.com/software-mansion/react-native-gesture-handler","tags":["javascript","typescript"],"install":[{"cmd":"npm install react-native-gesture-handler","lang":"bash","label":"npm"},{"cmd":"yarn add react-native-gesture-handler","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-native-gesture-handler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for React Native components.","package":"react","optional":false},{"reason":"Core dependency for React Native application development.","package":"react-native","optional":false}],"imports":[{"note":"Introduced in v3 for the new hook-based API, often used in conjunction with `Gesture` objects. `GestureDetector` is a named export.","wrong":"import GestureDetector from 'react-native-gesture-handler';","symbol":"GestureDetector","correct":"import { GestureDetector, Gesture } from 'react-native-gesture-handler';"},{"note":"Commonly used named export for individual gesture handlers, part of the older (v2.x) API. The `State` enum is also frequently imported for gesture state management.","wrong":"const TapGestureHandler = require('react-native-gesture-handler').TapGestureHandler;","symbol":"TapGestureHandler","correct":"import { TapGestureHandler, State } from 'react-native-gesture-handler';"},{"note":"A higher-order component (HOC) to wrap the root of your application, deprecated in v2.28.0. For v3 and newer projects, it's often replaced by `GestureHandlerRootView`.","symbol":"gestureHandlerRootHOC","correct":"import { gestureHandlerRootHOC } from 'react-native-gesture-handler';"},{"note":"A component that should wrap your entire application, necessary for gestures to work correctly on Android and other platforms, especially in new architecture setups. It's a named export from the main package.","wrong":"import { GestureHandlerRootView } from './GestureHandlerRootView';","symbol":"GestureHandlerRootView","correct":"import { GestureHandlerRootView } from 'react-native-gesture-handler';"}],"quickstart":{"code":"import React from 'react';\nimport { View, Text, StyleSheet } from 'react-native';\nimport { GestureDetector, Gesture } from 'react-native-gesture-handler';\nimport { GestureHandlerRootView } from 'react-native-gesture-handler';\n\nfunction AppContent() {\n  const [count, setCount] = React.useState(0);\n\n  // Define a simple tap gesture\n  const tapGesture = Gesture.Tap()\n    .onEnd(() => {\n      // This runs on the UI thread for performance\n      setCount(prev => prev + 1);\n    })\n    .numberOfTaps(1); // Respond to single taps\n\n  return (\n    <View style={styles.container}>\n      <GestureDetector gesture={tapGesture}>\n        <View style={styles.box}>\n          <Text style={styles.text}>Tap Me!</Text>\n          <Text style={styles.text}>Taps: {count}</Text>\n        </View>\n      </GestureDetector>\n    </View>\n  );\n}\n\n// It is crucial to wrap your entire application with GestureHandlerRootView\nexport default function App() {\n  return (\n    <GestureHandlerRootView style={{ flex: 1 }}>\n      <AppContent />\n    </GestureHandlerRootView>\n  );\n}\n\nconst styles = StyleSheet.create({\n  container: {\n    flex: 1,\n    justifyContent: 'center',\n    alignItems: 'center',\n    backgroundColor: '#F5FCFF',\n  },\n  box: {\n    width: 150,\n    height: 150,\n    backgroundColor: '#61dafb',\n    borderRadius: 20,\n    justifyContent: 'center',\n    alignItems: 'center',\n    padding: 20\n  },\n  text: {\n    fontSize: 20,\n    color: 'white',\n    fontWeight: 'bold',\n    textAlign: 'center'\n  }\n});\n","lang":"typescript","description":"Demonstrates a basic tap gesture using the `GestureDetector` and `Gesture` API (v3 style), incrementing a counter on tap. It includes the necessary `GestureHandlerRootView` wrapping the entire application."},"warnings":[{"fix":"Review the official migration guide for v3.0 (once stable) or the beta release blog post. Refactor old gesture handler components (e.g., `PanGestureHandler`) to the new `Gesture` and `GestureDetector` API.","message":"Version 3.0 introduces a new hook-based API (`GestureDetector`, `Gesture`) and significant internal changes tailored for the New Architecture. Projects upgrading from v2.x will require substantial code refactoring, especially for gesture definitions.","severity":"breaking","affected_versions":">=3.0.0-beta.1"},{"fix":"Replace usage of `gestureHandlerRootHOC` with `GestureHandlerRootView`. Wrap your main `App` component or the root of your application with `<GestureHandlerRootView style={{ flex: 1 }}>...</GestureHandlerRootView>`.","message":"The `gestureHandlerRootHOC` higher-order component was deprecated in favor of wrapping your app with `GestureHandlerRootView` for better compatibility and New Architecture support.","severity":"deprecated","affected_versions":">=2.28.0"},{"fix":"Ensure your top-level `App` component or the root of your component tree is wrapped within `<GestureHandlerRootView style={{ flex: 1 }}>...</GestureHandlerRootView>`.","message":"Gestures may not work correctly on Android or in applications using the New Architecture without wrapping the root component of your application with `GestureHandlerRootView`.","severity":"gotcha","affected_versions":">=2.x"},{"fix":"Always check the changelog for specific React Native version support. For example, v2.31.x supports RN 0.85, and v2.28.0 supports RN 0.81. Ensure your `react-native` and `react-native-gesture-handler` versions are aligned with the project's requirements.","message":"Compatibility with React Native versions is critical. Upgrading `react-native-gesture-handler` without updating `react-native` (or vice-versa) to compatible versions can lead to build errors or runtime issues.","severity":"gotcha","affected_versions":">=2.x"},{"fix":"If previously accessing `end` from a different scope or structure within these handlers, adjust your code to destructure it directly from the event object received by `onDeactivate` or `onFinalize`.","message":"In v3.0.0-beta.3, the event object passed to `onDeactivate` and `onFinalize` handlers now includes the `end` flag directly within the event object, which might require adjusting event destructuring.","severity":"breaking","affected_versions":">=3.0.0-beta.3"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Run `npx react-native link react-native-gesture-handler` (for older RN versions, though auto-linking is default now). Try clearing Metro cache (`npx react-native start --reset-cache`), clearing watchman watches (`watchman watch-del-all`), reinstalling node modules and pods (`rm -rf node_modules && yarn install && cd ios && pod install`). For Android, try `cd android && ./gradlew clean`.","cause":"The native module for react-native-gesture-handler is not correctly linked or initialized, often due to improper installation, outdated linking for older React Native versions, or caching issues.","error":"Invariant Violation: 'RNGestureHandlerModule' could not be found."},{"fix":"Ensure your application's root component is wrapped with `GestureHandlerRootView`. If using v3, verify `GestureDetector` wraps the interactive component. If using v2, ensure `gestureHandlerRootHOC` is applied or the specific `GestureHandler` component (e.g., `PanGestureHandler`) is correctly positioned in the component tree.","cause":"The `GestureHandlerRootView` is missing, or the component handling the gesture is not correctly wrapped by a `GestureDetector` (v3) or an appropriate `GestureHandler` component (v2), or the gesture handler hierarchy is incorrect.","error":"Gestures are not recognized or do not trigger any events."},{"fix":"Check the changelog for any changes to Touchable components. Ensure `react-native-gesture-handler` and its `@types/react-native` peer dependency are up to date. As of v2.31.1, fixes for Touchables TypeScript errors were applied, suggesting this was a known issue.","cause":"Specific Touchable components (e.g., `TouchableNativeFeedback`, `TouchableOpacity`) from `react-native-gesture-handler` might have changed their export or type definition, or there's a version mismatch with React Native types.","error":"TypeScript error: Property 'SomeTouchableComponent' does not exist on type 'typeof import(\"react-native-gesture-handler\")'"},{"fix":"Clean your Android project: `cd android && ./gradlew clean`. Ensure your `build.gradle` configuration isn't including `react-native-gesture-handler` multiple times or in conflicting ways. Rebuild the project. Sometimes deleting the `.gradle` folder in the project's root and in `android/.gradle` helps, followed by a full reinstall and `pod install` for iOS.","cause":"This usually indicates an issue with Android's dependency resolution, often due to mixing different versions or linking types of the library (e.g., direct and auto-linked), or a cached build issue.","error":"Android build error: Duplicate class com.swmansion.gesturehandler.BuildConfig found in modules jetified-react-native-gesture-handler... and react-native-gesture-handler..."}],"ecosystem":"npm"}