@amazon-devices/react-native-gesture-handler

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.

This is a system-deployed library and is available to KeplerScript apps without a separate installation process. It is deployed as an autolinking library which your app links to at runtime. Compatibility is guaranteed only between the library and the version of KeplerScript for which it is built.

When you upgrade the version of KeplerScript upon which your app is built, it is best practice to also upgrade the versions of the libraries that depend on KeplerScript.

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/.

Installation

1. Add the dependency in package.json file:

"dependencies": {
      ...
      "@amazon-devices/react-native-gesture-handler": "^2.0.0"
}

2. Reinstall package-lock.json file using npm install command.

Examples

Detecting single and double tapping.

import { Gesture, GestureDetector, GestureHandlerRootView } from '@amazon-devices/react-native-gesture-handler';
import React, { useEffect, useRef, useState } from 'react';
import { StyleSheet, Text, View } from 'react-native';

const App: React.FC = () => {
  const [message, setMessage] = useState("");
  const ref = useRef<View>(null);

  useEffect(() => {
    ref.current?.focus();
  }, [])

  const singleTap = Gesture.Tap().onStart(() => {
    setMessage("Single tap");
  });

  const doubleTap = Gesture.Tap().numberOfTaps(2).onStart(() => {
    setMessage("Double tap")
  });

  return (
    <GestureHandlerRootView style={{flex: 1}}>
      <View style={styles.container}>
        <Text>Tap the box once or twice</Text>
        <GestureDetector gesture={Gesture.Exclusive(doubleTap, singleTap)}>
          <View style={styles.box} focusable ref={ref} />
        </GestureDetector>
        <Text>{message}</Text>
      </View>
    </GestureHandlerRootView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: 'white',
    alignItems: 'center',
    justifyContent: 'center'
  },
  box: {
    width: 200,
    height: 200,
    backgroundColor: 'plum',
    margin: 20,
  }
});

export default App;

Moving the box with Pan gesture handler.

import { Gesture, GestureDetector, GestureHandlerRootView } from '@amazon-devices/react-native-gesture-handler';
import React, { useEffect, useRef, useState } from 'react';
import { StyleSheet, Text, View } from 'react-native';

const App: React.FC = () => {
  const [posX, setPosX] = useState(0);
  const [posY, setPosY] = useState(0);
  const ref = useRef<View>(null);

  useEffect(() => {
    ref.current?.focus();
  }, [])

  const pan = Gesture.Pan().onChange((e) => {
    setPosX((x) => x + e.changeX);
    setPosY((y) => y + e.changeY);
  })

  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <View style={styles.container}>
        <Text>Drag the box across the screen</Text>
        <GestureDetector gesture={pan}>
          <View style={[styles.box, { top: posY, left: posX }]} focusable ref={ref} />
        </GestureDetector>
      </View>
    </GestureHandlerRootView>
  );
};

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: 'white',
    alignItems: 'center',
    justifyContent: 'center'
  },
  box: {
    width: 200,
    height: 200,
    backgroundColor: 'plum',
    margin: 20,
  }
});

export default App;

API supported on Kepler

Gesture-Handler library on Kepler adds a support for all gesture types and native components listed in the official documentation.

Gesture types

| gesture type | description | platform | | ------- | -------------------- | -------------------- | | Pan | A continuous gesture handler that can recognize a panning (dragging) gesture and track its movement. | All | | Tap | A discrete gesture handler that recognizes one or many taps. | All | | Long press | A discrete gesture handler that activates when the corresponding view is pressed for a sufficiently long time. | All | | Rotation | A continuous gesture handler that can recognize a rotation gesture and track its movement. | All | | Pinch | A continuous gesture handler that recognizes pinch gesture. It allows for tracking the distance between two fingers and use that information to scale or zoom your content. | All | | Fling | A discrete gesture handler that activates when the movement is sufficiently long and fast. | All | | Manual | A plain gesture that has no specific activation criteria nor event data set. The app developers must handle the state programmatically in their application logic using a gesture state manager. | All |

Native components

| native component | description | platform | | ------- | -------------------- | -------------------- | | RNGestureHandlerButton | Gesture handler library provides native components that can act as buttons. These can be treated as a replacement to TouchableHighlight or TouchableOpacity from RN core. | All |

Supported react-native-kepler versions

| @amazon-devices/react-native-gesture-handler version | @amazon-devices/react-native-kepler version | | ------------------------------------------ | --------------------------------- | | 2.13.0 | 2.0.0+rn0.72.0 |

Credits

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