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

Declarative API exposing platform native touch and gesture system to React Native.

React Native Gesture Handler provides native-driven gesture management APIs for building best possible touch-based experiences in React Native.

With this library gestures are no longer controlled by the JS responder system, but instead are recognized and tracked in the UI thread. It makes touch interactions and gesture tracking not only smooth, but also dependable and deterministic.

Installation

Check getting started section of our docs for the detailed installation instructions.

Fabric

To learn how to use react-native-gesture-handler with Fabric architecture, head over to Fabric README. Instructions on how to run Fabric Example within this repo can be found in the FabricExample README.

Documentation

Check out our dedicated documentation page for info about this library, API reference and more: https://docs.swmansion.com/react-native-gesture-handler/docs/

Examples

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

yarn install

Run yarn start to start the metro bundler

Run yarn android or yarn ios (depending on which platform you want to run the example app on).

You will need to have an Android or iOS device or emulator connected.

React Native Support

version	react-native version
2.18.0+	0.73.0+
2.16.0+	0.68.0+
2.14.0+	0.67.0+
2.10.0+	0.64.0+
2.0.0+	0.63.0+
1.4.0+	0.60.0+
1.1.0+	0.57.2+
<1.1.0	0.50.0+

It may be possible to use newer versions of react-native-gesture-handler on React Native with version <= 0.59 by reverse Jetifying. Read more on that here https://github.com/mikehardy/jetifier#to-reverse-jetify--convert-node_modules-dependencies-to-support-libraries

License

Gesture handler library is licensed under The MIT License.

Credits

This project has been build and is maintained thanks to the support from Shopify, Expo.io and Software Mansion

Community Discord

Join the Software Mansion Community Discord to chat about Gesture Handler or other Software Mansion libraries.

Gesture Handler is created by Software Mansion

Since 2012 Software Mansion is a software agency with experience in building web and mobile apps. We are Core React Native Contributors and experts in dealing with all kinds of React Native issues. We can help you build your next dream product – Hire us.