Getting Started

Gesture Handler aims to replace React Native's built in touch system called Gesture Responder System.

The motivation for building this library was to address the performance limitations of React Native's Gesture Responder System and to provide more control over the built-in native components that can handle gestures. We recommend this talk by Krzysztof Magiera in which he explains issues with the responder system.

In a nutshell, the library provides:

  • A way to use a platform's native touch handling system for recognizing pinch, rotation and pan (besides a few other gestures).
  • The ability to define relations between gesture handlers, e.g. when you have a pan handler in ScrollView you can make that ScrollView wait until it knows pan won't recognize.
  • Mechanisms to use touchables that run in native thread and follow platform default behavior; e.g. in the event they are in a scrollable component, turning into pressed state is slightly delayed to prevent it from highlighting when you fling.
  • The possibility to implement smooth gesture interactions thanks to Animated Native Driver — interactions will be responsive even when the JS thread is overloaded.


Managed Expo

To use the version of react-native-gesture-handler that is compatible with your managed Expo project, run expo install react-native-gesture-handler.

The Expo SDK incorporates the latest version of react-native-gesture-handler available at the time of each SDK release, so managed Expo apps might not always support all our latest features as soon as they are available.

Bare React Native

Since the library uses native support for handling gestures, it requires an extended installation to the norm. If you are starting a new project, you may want to initialize it with expo-cli and use a bare template, they come pre-installed with react-native-gesture-handler.


versionreact-native version

Note that if you wish to use React.createRef() support for interactions you need to use v16.3 of React


First, install the library using yarn:

yarn add react-native-gesture-handler

or with npm if you prefer:

npm install --save react-native-gesture-handler


Important: You only need to do this step if you're using React Native 0.59 or lower. Since v0.60, linking happens automatically.

react-native link react-native-gesture-handler


Follow the steps below:

If you use one of the native navigation libraries (e.g. wix/react-native-navigation), you should follow this separate guide to get gesture handler library set up on Android. Ignore the rest of this step – it only applies to RN apps that use a standard Android project layout.


Update your file (or wherever you create an instance of ReactActivityDelegate), so that it overrides the method responsible for creating ReactRootView instance and then use the root view wrapper provided by this library. Do not forget to import ReactActivityDelegate, ReactRootView, and RNGestureHandlerEnabledRootView:

package com.swmansion.gesturehandler.react.example;
import com.facebook.react.ReactActivity;
+ import com.facebook.react.ReactActivityDelegate;
+ import com.facebook.react.ReactRootView;
+ import com.swmansion.gesturehandler.react.RNGestureHandlerEnabledRootView;
public class MainActivity extends ReactActivity {
protected String getMainComponentName() {
return "Example";
+ @Override
+ protected ReactActivityDelegate createReactActivityDelegate() {
+ return new ReactActivityDelegate(this, getMainComponentName()) {
+ @Override
+ protected ReactRootView createRootView() {
+ return new RNGestureHandlerEnabledRootView(MainActivity.this);
+ }
+ };
+ }
Running jetifier

Important: You only need to do this step if you're on React Native 0.60 or greater.

React Native 0.60 migrated from Support Library to AndroidX. React Native Gesture Handler is not yet compatible with AndroidX.

Make sure to update the React Native CLI to the latest version which runs jetifier – the AndroidX migration tool – during the run-android command.


There is no additional configuration required on iOS except what follows in the next steps.

If you're in a CocoaPods project (the default setup since React Native 0.60), make sure to install pods before you run your app:

cd ios && pod install

For React Native 0.61 or greater, add the library as the first import in your index.js file:

import 'react-native-gesture-handler';

Now you're all set. Run your app with react-native run-android or react-native run-ios.

With wix/react-native-navigation

If you are using a native navigation library like wix/react-native-navigation you need to follow a different setup for your Android app to work properly. The reason is that both native navigation libraries and Gesture Handler library need to use their own special subclasses of ReactRootView.

Instead of changing Java code you will need to wrap every screen component using gestureHandlerRootHOC on the JS side. This can be done for example at the stage when you register your screens. Here's an example:

import { gestureHandlerRootHOC } from 'react-native-gesture-handler';
import { Navigation } from 'react-native-navigation';
import FirstTabScreen from './FirstTabScreen';
import SecondTabScreen from './SecondTabScreen';
import PushedScreen from './PushedScreen';
// register all screens of the app (including internal ones)
export function registerScreens() {
() => gestureHandlerRootHOC(FirstTabScreen),
() => FirstTabScreen
() => gestureHandlerRootHOC(SecondTabScreen),
() => SecondTabScreen
() => gestureHandlerRootHOC(PushedScreen),
() => PushedScreen

You can check out this example project to see this kind of set up in action.

Remember that you need to wrap each screen that you use in your app with gestureHandlerRootHOC as with native navigation libraries each screen maps to a separate root view. It will not be enough to wrap the main screen only.

Usage with modals on Android

On Android RNGH does not work by default because modals are not located under React Native Root view in native hierarchy. In order to make it workable, components need to be wrapped with gestureHandlerRootHOC (it's no-op on iOS and web).


const ExampleWithHoc = gestureHandlerRootHOC(function GestureExample() {
return (
<DraggableBox />
export default function Example() {
return (
<Modal animationType="slide" transparent={false}>
<ExampleWithHoc />

For library authors

If you're using gesture handler in your component library, you may want to wrap your library's code in the GestureHandlerRootView component. This will avoid extra configuration in for the user.

import { GestureHandlerRootView } from 'react-native-gesture-handler';
export default MyComponent() {
return (
{/* content */}

If you use props such as shouldCancelWhenOutside, simultaneousHandlers, waitFor etc. with gesture handlers, the handlers need to be mounted under a single GestureHandlerRootView. So it's important to keep the GestureHandlerRootView as close to the actual root view as possible.

Note that GestureHandlerRootView acts like a normal View. So if you want it to fill the screen, you will need to pass { flex: 1 } like you'll need to do with a normal View. By default, it'll take the size of the content nested inside.


In order to load mocks provided by the library add following to your jest config in package.json:

"setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"]


"jest": {
"preset": "react-native",
"setupFiles": ["./node_modules/react-native-gesture-handler/jestSetup.js"]