Skip to main content
Version: 3.x

Installation

Requirements​

Compatibility with React Native versions​

react-native-gesture-handler supports the three latest minor releases of react-native.

0.820.83
3.0.0-beta.1
yes
yes

Running gestures on the UI thread​

Using Reanimated is the recommended method of handling gesture-driven interactions on the UI thread. In order to use it, you need to install react-native-reanimated along with react-native-worklets. Another approach is to use React Native's Animated API.

For more details on how to implement these, refer to the dedicated sections for Reanimated and Animated.

Setup​

Setting up react-native-gesture-handler is pretty straightforward:

1. Start with installing the package from npm:​

npx expo install react-native-gesture-handler

2. Wrap your app with GestureHandlerRootView component​

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

export default function App() {
  return (
    <GestureHandlerRootView>
      <ActualApp />
    </GestureHandlerRootView>
  );
}

Keep GestureHandlerRootView as close to the actual root of the app as possible. It's the entry point for all gestures and all gesture relations. The gestures won't be recognized outside of the root view, and relations only work between gestures mounted under the same root view.

Check out GestureHandlerRootView section for more details.

3. Platform specific setup​

Expo development build​

When using an Expo development build, run prebuild to update the native code in the ios and android directories.

npx expo prebuild

Android​

Setting up Gesture Handler on Android doesn't require any more steps. Keep in mind that if you want to use gestures in Modals you need to wrap Modal's content with GestureHandlerRootView:

import { Modal } from 'react-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';

export function CustomModal({ children, ...rest }) {
  return (
    <Modal {...rest}>
      <GestureHandlerRootView>{children}</GestureHandlerRootView>
    </Modal>
  );
}

Gesture Handler on Android is implemented in Kotlin. If you need to set a specific Kotlin version to be used by the library, set the kotlinVersion ext property in android/build.gradle file and RNGH will use that version:

buildscript {
    ext {
        kotlinVersion = "2.1.20"
    }
}

iOS​

While developing for iOS, make sure to install pods first before running the app:

cd ios && bundle install && bundle exec pod install && cd ..

macOS​

While developing for macOS, make sure to install pods first before running the app:

cd macos && bundle install && bundle exec pod install && cd ..

Web​

There is no additional configuration required for the web.

With wix/react-native-navigation​

If you are using a native navigation library like wix/react-native-navigation you need to make sure that every screen is wrapped with GestureHandlerRootView. This can be done for example at the stage when you register your screens. Here's an example:

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() {
  Navigation.registerComponent(
    'example.FirstTabScreen',
    () => {
      return (
        <GestureHandlerRootView>
          <FirstTabScreen />
        </GestureHandlerRootView>
      );
    },
    () => FirstTabScreen
  );
  Navigation.registerComponent(
    'example.SecondTabScreen',
    () => {
      return (
        <GestureHandlerRootView>
          <SecondTabScreen />
        </GestureHandlerRootView>
      );
    },
    () => SecondTabScreen
  );
  Navigation.registerComponent(
    'example.PushedScreen',
    () => {
      return (
        <GestureHandlerRootView>
          <PushedScreen />
        </GestureHandlerRootView>
      );
    },
    () => PushedScreen
  );
}

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