getting-started.md

id	getting-started
title	Getting Started
sidebar_label	Getting Started

Gesture handler aims at replacing React Native's built in touch system called a JS Responder System.

The motivations for building this library were to address performance limitations of the responder system and to provide more control over the built in native components that can handle gestures. We recommend this talk by Krzysztof Magiera where the issues with the responder system are explained.

Here is what the library provides in a nutshell:

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

Installation

As library uses native support for handling gestures it requires custom installation.

With React Native app (no Expo)

Requirements

In order to install the newest version of a library it's requires to use v0.50+ of React Native.

Mind that if your wish to use React.createRef() support for interactions you need to use v.16.3 of React

JS

First install the library from npm repository using yarn:

  yarn add react-native-gesture-handler

or using npm if you prefer:

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

Linking

  react-native link react-native-gesture-handler

Android

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 standard Android project layout.

Update your main activity (or wherever you create an instance of ReactActivityDelegate), so that it overrides the method responsible for creating ReactRootView instance. Then use a root view wrapper provided by this library:

// Don't forget imports
import com.facebook.react.ReactActivityDelegate;
import com.facebook.react.ReactRootView;
import com.swmansion.gesturehandler.react.RNGestureHandlerEnabledRootView;

public class MainActivity extends ReactActivity {

  // Add the following method to your main activity class
  @Override
  protected ReactActivityDelegate createReactActivityDelegate() {
    return new ReactActivityDelegate(this, getMainComponentName()) {
      @Override
      protected ReactRootView createRootView() {
        return new RNGestureHandlerEnabledRootView(MainActivity.this);
      }
    };
  }
}

iOS

There is no additional config required to be done on iOS except from what follows in the next steps.

---

Now You're all set, just run your app with react-native run-android or react-native run-ios

With Expo

As gesture handler is already part of Expo, there's no need to add any extra configuration. However, consider that Expo SDK could to include the newest version of the library so it might not support newest features.

With wix/react-native-navigation

If you are using 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 is 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() {
  Navigation.registerComponent('example.FirstTabScreen', () =>
    gestureHandlerRootHOC(FirstTabScreen));
  Navigation.registerComponent('example.SecondTabScreen', () =>
    gestureHandlerRootHOC(SecondTabScreen));
  Navigation.registerComponent('example.PushedScreen', () =>
    gestureHandlerRootHOC(PushedScreen));
}

You can check this example project to see this 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 is not enough to wrap the main screen only.