react-native-gesture-handler

What is react-native-gesture-handler?

react-native-gesture-handler is a library that provides native-driven gesture management APIs for building smooth and responsive gesture-based interactions in React Native applications. It offers a wide range of gesture handlers and components to handle touch and gesture events more efficiently than the default gesture system in React Native.

What are react-native-gesture-handler's main functionalities?

Tap Gesture

This feature allows you to detect tap gestures on a component. The code sample demonstrates how to use the TapGestureHandler to detect a tap on a View component.

import { TapGestureHandler, State } from 'react-native-gesture-handler';
import { View, Text } from 'react-native';

function MyComponent() {
  const onHandlerStateChange = (event) => {
    if (event.nativeEvent.state === State.ACTIVE) {
      console.log('Tap gesture detected');
    }
  };

  return (
    <TapGestureHandler onHandlerStateChange={onHandlerStateChange}>
      <View style={{ width: 100, height: 100, backgroundColor: 'blue' }}>
        <Text>Tap me</Text>
      </View>
    </TapGestureHandler>
  );
}

Pan Gesture

This feature allows you to detect and respond to pan gestures, which involve dragging a component. The code sample demonstrates how to use the PanGestureHandler to move a View component based on user drag gestures.

import { PanGestureHandler, State } from 'react-native-gesture-handler';
import { View, Animated } from 'react-native';

function MyComponent() {
  const translateX = new Animated.Value(0);
  const translateY = new Animated.Value(0);

  const onGestureEvent = Animated.event([
    {
      nativeEvent: {
        translationX: translateX,
        translationY: translateY,
      },
    },
  ], { useNativeDriver: true });

  const onHandlerStateChange = (event) => {
    if (event.nativeEvent.state === State.END) {
      translateX.setValue(0);
      translateY.setValue(0);
    }
  };

  return (
    <PanGestureHandler
      onGestureEvent={onGestureEvent}
      onHandlerStateChange={onHandlerStateChange}
    >
      <Animated.View style={{ transform: [{ translateX }, { translateY }] }}>
        <View style={{ width: 100, height: 100, backgroundColor: 'red' }} />
      </Animated.View>
    </PanGestureHandler>
  );
}

Pinch Gesture

This feature allows you to detect pinch gestures, which involve two fingers moving closer together or further apart. The code sample demonstrates how to use the PinchGestureHandler to scale a View component based on pinch gestures.

import { PinchGestureHandler, State } from 'react-native-gesture-handler';
import { View, Animated } from 'react-native';

function MyComponent() {
  const scale = new Animated.Value(1);

  const onGestureEvent = Animated.event([
    {
      nativeEvent: { scale: scale },
    },
  ], { useNativeDriver: true });

  const onHandlerStateChange = (event) => {
    if (event.nativeEvent.state === State.END) {
      Animated.spring(scale, {
        toValue: 1,
        useNativeDriver: true,
      }).start();
    }
  };

  return (
    <PinchGestureHandler
      onGestureEvent={onGestureEvent}
      onHandlerStateChange={onHandlerStateChange}
    >
      <Animated.View style={{ transform: [{ scale }] }}>
        <View style={{ width: 100, height: 100, backgroundColor: 'green' }} />
      </Animated.View>
    </PinchGestureHandler>
  );
}

Other packages similar to react-native-gesture-handler

react-native-reanimated

react-native-reanimated is a library that provides a more powerful and flexible way to create animations in React Native. It allows for complex gesture interactions and animations to be defined in JavaScript and executed on the native thread, resulting in smoother performance. While it focuses more on animations, it can be used in conjunction with gesture handlers to create advanced gesture-based animations.

react-native-swipe-gestures

react-native-swipe-gestures is a library that provides easy-to-use swipe gesture detection for React Native applications. It is simpler and more limited in scope compared to react-native-gesture-handler, focusing primarily on detecting swipe gestures in four directions (up, down, left, right). It is suitable for applications that need basic swipe gesture detection without the complexity of handling multiple types of gestures.

react-native-draggable

react-native-draggable is a library that provides draggable components for React Native applications. It allows you to make any component draggable with minimal setup. While it is more focused on drag-and-drop interactions, it does not offer the same breadth of gesture handling capabilities as react-native-gesture-handler.

README

react-native-gesture-handler

This is an experimental implementation of a new declarative API for gesture handling in react-native. The project is Android only at the moment and works by completely replacing current react native touch system, which means that all Touchable and PanResponder components you may use in your app will not function as expected.

Installation

I. First install the library from npm repository:

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

II. Update your main activity (or wherever you create an instance of ReactActivityDelegate), so that it overrides the method responsible for creating a 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;

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);
      }
    };
  }
}

III. Run:

  react-native link react-native-gesture-handler

IV. You're all set, just run your app with react-native run-android

Examples

If you don't feel like trying it on a real app, but just want to play with the API you can run the example project. Clone the repo, go to the Example/ folder and run:

  npm install && react-native run-android

You will need to have an android device or emulator connected as well as react-native-cli package installed globally.

API

Here are a gesture recognizers currently available in the package:

• TapGestureHandler
• LongPressGestureHandler
• PanGestureHandler

Whenever you use a native component that should handle touch events you can either wrap it with NativeViewGestureHandler or import wrapper component exported by the library instead iporting it from react-native package. Here is the list of available components:

• Slider
• Switch
• TextInput
• ToolbarAndroid
• ViewPagerAndroid
• WebView
• NativeViewGestureHandler

Last available element exported by the library is a dictionary of constants used to express the state of the recognizer. Here are the available options:

• State.UNDETERMINED
• State.FAILED
• State.BEGAN
• State.CANCELLED
• State.ACTIVE
• State.END

Common GestureHandler properties

• shouldCancelWhenOutside
• shouldCancelOthersWhenActivated
• shouldBeRequiredByOthersToFail
• onGestureEvent
• onHandlerStateChange

TapGestureHandler extra properties

• maxDurationMs
• maxDelayMs
• numberOfTaps

NativeViewGestureHandler extra properties

• shouldActivateOnStart

LongPressGestureHandler extra properties

• minDurationMs

PanGestureHandler extra properties

• minDeltaX
• minDeltaY
• minDist
• maxVelocity

Roadmap

• Build one more gesture recognizer: FlingGestureHandler
• Send out necessary updates to RN core for native animated event support
• Support for multi-touch events (build PinchGestureHandler)
• iOS port

Troubleshooting

This project is very experimental so it is not suprising you're seeking help. Try searching over the issues on GitHub here. If you don't find anything that would help feel free to open a new issue!

Contributing

If you are interested in the project and want to contribute or support it in other ways don't hesitate to contact me! Also all PRs are always welcome!