installation.mdx

id	installation
title	Installation
sidebar_position	2

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

import { GestureHandlerCompatibility } from '../../components/Compatibility';

Requirements

Compatibility with React Native versions

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

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:

```bash npx expo install react-native-gesture-handler ``` ```bash npm install react-native-gesture-handler ``` ```bash yarn add 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 the 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.