xref: /expo/docs/pages/tutorial/gestures.mdx (revision 72bb203a)

---
title: Add gestures
---

import { SnackInline, Terminal } from '~/ui/components/Snippet';
import Video from '~/components/plugins/Video';
import { A } from '~/ui/components/Text';
import { Step } from '~/ui/components/Step';
import { BoxLink } from '~/ui/components/BoxLink';
import { BookOpen02Icon } from '@expo/styleguide-icons';

Gestures are a great way to provide an intuitive user experience in an app. The [React Native Gesture Handler library](https://docs.swmansion.com/react-native-gesture-handler/docs/) provides built-in native components that can handle gestures.
It uses the platform's native touch handling system to recognize pan, tap, rotation, and other gestures.

In this chapter, we are going to add two different gestures using the React Native Gesture Handler library:

- Double tap to scale the size of the emoji sticker.
- Pan to move the emoji sticker around the screen so that the user can place the sticker anywhere on the image.

<Step label="1">

## Install and configure libraries

The React Native Gesture Handler library provides a way to interact with the native platform's gesture response system.
To animate between gesture states, we will use the [Reanimated library](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/handling-gestures).

To install them, stop the development server by pressing <kbd>Ctrl</kbd> + <kbd>c</kbd> and run the following command in the terminal:

<Terminal cmd={['$ npx expo install react-native-gesture-handler react-native-reanimated']} />

Next, also install `@babel/plugin-proposal-export-namespace-from`, which is required to configure the Reanimated library:

<Terminal cmd={['$ npm install -D @babel/plugin-proposal-export-namespace-from ']} />

Then, add Reanimated's Babel plugin to **babel.config.js**:

{/* prettier-ignore */}
```jsx babel.config.js
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    /* @info Add the plugins array and inside it, add the plugins.*/
    plugins: [
      "@babel/plugin-proposal-export-namespace-from",
      "react-native-reanimated/plugin",
    ],
    /* @end */
  };
};
```

Now, start the development server again:

<Terminal cmd={['$ npx expo start -c']} />

> **Tip**: We are using `-c` option here because we modified the **babel.config.js** file.

To get gesture interactions to work in the app, we'll render `<GestureHandlerRootView>` from `react-native-gesture-handler` to wrap the top-level component of our app (also known as the "root component").

To accomplish this, replace the root level `<View>` component in the **App.js** with `<GestureHandlerRootView>`.

{/* prettier-ignore */}
```jsx App.js
/* @info Import GestureHandlerRootView from react-native-gesture-handler-library. */import { GestureHandlerRootView } from "react-native-gesture-handler"; /* @end */

export default function App() {
  return (
    /* @info Replace the root level View component with GestureHandlerRootView. */<GestureHandlerRootView style={styles.container}> /* @end */
    /* ...rest of the code remains */
    /* @info */</GestureHandlerRootView>/* @end */
  )
}
```

</Step>

<Step label="2">

## Create animated components

Open the **EmojiSticker.js** file in the **components** directory. Inside it, import `Animated` from the `react-native-reanimated` library to create animated components.

```jsx EmojiSticker.js
import Animated from 'react-native-reanimated';
```

To make a double tap gesture work, we will apply animations to the `<Image>` component by passing it as an argument to the `Animated.createAnimatedComponent()` method.

```jsx EmojiSticker.js
// after import statements, add the following line

const AnimatedImage = Animated.createAnimatedComponent(Image);
```

The `createAnimatedComponent()` can wrap any component. It looks at the `style` prop of the component, determines which value is animated, and then applies updates to create an animation.

Replace the `<Image>` component with `<AnimatedImage>`.

{/* prettier-ignore */}
```jsx EmojiSticker.js
export default function EmojiSticker({ imageSize, stickerSource }) {
  return (
    <View style={{ top: -350 }}>
      /* @info Replace the Image component with AnimatedImage. */<AnimatedImage /* @end */
        source={stickerSource}
        resizeMode="contain"
        style={{ width: imageSize, height: imageSize }}
      />
    </View>
  );
}
```

</Step>

<Step label="3">

## Add a tap gesture

React Native Gesture Handler allows us to add behavior when it detects touch input, like a double tap event.

In the **EmojiSticker.js** file, import `TapGestureHandler` from `react-native-gesture-handler` and the hooks below from `react-native-reanimated`.
These hooks will animate the style on the `<AnimatedImage>` component for the sticker when the tap gesture is recognized.

```jsx EmojiSticker.js
import { TapGestureHandler } from 'react-native-gesture-handler';
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  useAnimatedGestureHandler,
  withSpring,
} from 'react-native-reanimated';
```

Inside the `<EmojiSticker>` component, create a reference called `scaleImage` using the `useSharedValue()` hook. It will take the value of `imageSize` as its initial value.

```jsx EmojiSticker.js
const scaleImage = useSharedValue(imageSize);
```

Creating a shared value using the `useSharedValue()` hook has many advantages. It helps to mutate a piece of data and allows running animations based on the current value.
A shared value can be accessed and modified using the `.value` property. It will scale the initial value of `scaleImage` so that when a user double-taps the sticker,
it scales to twice its original size. To do this, we will create a function and call it `onDoubleTap()`, and this function will use the `useAnimatedGestureHandler()` hook
to animate the transition while scaling the sticker image.

Create the following function in the `<EmojiSticker>` component:

```jsx EmojiSticker.js
const onDoubleTap = useAnimatedGestureHandler({
  onActive: () => {
    if (scaleImage.value !== imageSize * 2) {
      scaleImage.value = scaleImage.value * 2;
    }
  },
});
```

To animate the transition, let's use a spring-based animation. This will make it feel alive because it's based on the real-world physics of a spring.
We will use the `withSpring()` hook provided by `react-native-reanimated`.

The `useAnimatedStyle()` hook from `react-native-reanimated` is used to create a style object that will be applied to the sticker image.
It will update styles using the shared values when the animation happens. In this case, we are scaling the size of the image,
which is done by manipulating the `width` and `height` properties. The initial values of these properties are set to `imageSize`.
Create an `imageStyle` variable and add it to the `EmojiSticker` component:

```jsx EmojiSticker.js
const imageStyle = useAnimatedStyle(() => {
  return {
    width: withSpring(scaleImage.value),
    height: withSpring(scaleImage.value),
  };
});
```

Next, wrap the `<AnimatedImage>` component that displays the sticker on the screen with the `<TapGestureHandler>` component.

<SnackInline
label="Handling tap gesture"
templateId="tutorial/06-gestures/App"
dependencies={['expo-image-picker', '@expo/vector-icons/FontAwesome', '@expo/vector-icons', 'expo-status-bar', '@expo/vector-icons/MaterialIcons', 'react-native-gesture-handler', 'react-native-reanimated']}
files={{
  'assets/images/background-image.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/503001f14bb7b8fe48a4e318ad07e910',
  'assets/images/emoji1.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/be9751678c0b3f9c6bf55f60de815d30',
  'assets/images/emoji2.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/7c0d14b79e134d528c5e0801699d6ccf',
  'assets/images/emoji3.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/d713e2de164764c2ab3db0ab4e40c577',
  'assets/images/emoji4.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/ac2163b98a973cb50bfb716cc4438f9a',
  'assets/images/emoji5.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/9cc0e2ff664bae3af766b9750331c3ad',
  'assets/images/emoji6.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/ce614cf0928157b3f7daa3cb8e7bd486',
  'components/ImageViewer.js': 'tutorial/02-image-picker/ImageViewer.js',
  'components/Button.js': 'tutorial/03-button-options/Button.js',
  'components/CircleButton.js': 'tutorial/03-button-options/CircleButton.js',
  'components/IconButton.js': 'tutorial/03-button-options/IconButton.js',
  'components/EmojiPicker.js': 'tutorial/04-modal/EmojiPicker.js',
  'components/EmojiList.js': 'tutorial/05-emoji-list/EmojiList.js',
  'components/EmojiSticker.js': 'tutorial/06-gestures/EmojiSticker.js',
}}>

{/* prettier-ignore */}
```jsx
export default function EmojiSticker({ imageSize, stickerSource }) {
  // ...rest of the code remains same
  return (
    <View style={{ top: -350 }}>
      /* @info Wrap the AnimatedImage component with TapGestureHandler*/ <TapGestureHandler onGestureEvent={onDoubleTap} numberOfTaps={2}>/* @end */
        <AnimatedImage
          source={stickerSource}
          resizeMode="contain"
          /* @info Modify the style prop on the AnimatedImage to pass the imageStyle.*/ style={[imageStyle, { width: imageSize, height: imageSize }]} /* @end */
        />
      /* @info */</TapGestureHandler>/* @end */
    </View>
  );
}
```

</SnackInline>

In the above snippet, the `onGestureEvent` prop takes the value of the `onDoubleTap()` function and triggers it when a user taps the sticker image.
The `numberOfTaps` prop determines how many taps are required.

Let's take a look at our app on iOS, Android and the web:

<Video file="tutorial/tap-gesture.mp4" />

> For a complete reference on the tap gesture API, refer to the [React Native Gesture Handler](https://docs.swmansion.com/react-native-gesture-handler/docs/api/gestures/tap-gesture) documentation.

</Step>

<Step label="4">

## Add a pan gesture

A pan gesture allows recognizing a dragging gesture and tracking its movement. We will use this gesture handler to drag the sticker across the image.

In the **EmojiSticker.js**, import `PanGestureHandler` from the `react-native-gesture-handler` library.

{/* prettier-ignore */}
```jsx EmojiSticker.js
import { /* @info */ PanGestureHandler,/* @end */ TapGestureHandler} from "react-native-gesture-handler";
```

Create an `<AnimatedView>` component using the `Animated.createAnimatedComponent()` method. Then use it to wrap the `<TapGestureHandler>` component by replacing the `<View>` component.

{/* prettier-ignore */}
```jsx EmojiSticker.js
// ...rest of the code remains same
/* @info */ const AnimatedView = Animated.createAnimatedComponent(View); /* @end */

export default function EmojiSticker({ imageSize, stickerSource }) {
  // ...rest of the code remains same

  return (
    /* @info Replace the View component with AnimatedView */<AnimatedView style={{ top: -350 }}>/* @end */
      <TapGestureHandler onGestureEvent={onDoubleTap} numberOfTaps={2}>
        {/* ...rest of the code remains same */}
      </TapGestureHandler>
    /* @info */</AnimatedView>/* @end */
  );
}
```

Now, create two new shared values: `translateX` and `translateY`.

```jsx EmojiSticker.js
export default function EmojiSticker({ imageSize, stickerSource }) {
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);

  // ...rest of the code remains same
}
```

These translation values will move the sticker around the screen. Since the sticker moves along both axes, we need to track the X and Y values separately.

In the `useSharedValue()` hooks, we have set both translation variables to have an initial position of `0`.
This means that the position the sticker is initially placed is considered the starting point. This value sets the initial position of the sticker when the gesture starts.

In the previous step, we triggered the `onActive()` callback for the tap gesture inside the `useAnimatedGestureHandler()` function.
Similarly, for the pan gesture, we have to specify two callbacks:

- `onStart()`: when the gesture starts or is at its initial position
- `onActive()`: when the gesture is active and is moving

Create an `onDrag()` method to handle the pan gesture.

{/* prettier-ignore */}
```jsx EmojiSticker.js
const onDrag = useAnimatedGestureHandler({
  onStart: (event, context) => {
    context.translateX = translateX.value;
    context.translateY = translateY.value;
  },
  onActive: (event, context) => {
    translateX.value = event.translationX + context.translateX;
    translateY.value = event.translationY + context.translateY;
  },
});
```

Both the `onStart` and `onActive` methods accept `event` and `context` as parameters. In the `onStart` method, we'll use `context` to store the initial values of `translateX` and `translateY`. In the `onActive` callback, we'll use the `event` to get the current position of the pan gesture and `context` to get the previously stored values of `translateX` and `translateY`.

Next, use the `useAnimatedStyle()` hook to return an array of transforms.For the `<AnimatedView>` component, we need to set the `transform` property to the `translateX` and `translateY` values. This will change the sticker's position when the gesture is active.

{/* prettier-ignore */}
```jsx EmojiSticker.js
const containerStyle = useAnimatedStyle(() => {
  return {
    transform: [
      {
        translateX: translateX.value,
      },
      {
        translateY: translateY.value,
      },
    ],
  };
});
```

Then add the `containerStyle` from the above snippet on the `<AnimatedView>` component to apply the transform styles.
Also, update the `<EmojiSticker>` component so that the `<PanGestureHandler>` component becomes the top-level component.

<SnackInline
label="Handle pan gesture"
templateId="tutorial/06-gestures/App"
dependencies={['expo-image-picker', '@expo/vector-icons/FontAwesome', '@expo/vector-icons', 'expo-status-bar', '@expo/vector-icons/MaterialIcons', 'react-native-gesture-handler', 'react-native-reanimated']}
files={{
  'assets/images/background-image.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/503001f14bb7b8fe48a4e318ad07e910',
  'assets/images/emoji1.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/be9751678c0b3f9c6bf55f60de815d30',
  'assets/images/emoji2.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/7c0d14b79e134d528c5e0801699d6ccf',
  'assets/images/emoji3.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/d713e2de164764c2ab3db0ab4e40c577',
  'assets/images/emoji4.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/ac2163b98a973cb50bfb716cc4438f9a',
  'assets/images/emoji5.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/9cc0e2ff664bae3af766b9750331c3ad',
  'assets/images/emoji6.png': 'https://snack-code-uploads.s3.us-west-1.amazonaws.com/~asset/ce614cf0928157b3f7daa3cb8e7bd486',
  'components/ImageViewer.js': 'tutorial/02-image-picker/ImageViewer.js',
  'components/Button.js': 'tutorial/03-button-options/Button.js',
  'components/CircleButton.js': 'tutorial/03-button-options/CircleButton.js',
  'components/IconButton.js': 'tutorial/03-button-options/IconButton.js',
  'components/EmojiPicker.js': 'tutorial/04-modal/EmojiPicker.js',
  'components/EmojiList.js': 'tutorial/05-emoji-list/EmojiList.js',
  'components/EmojiSticker.js': 'tutorial/06-gestures/CompleteEmojiSticker.js',
}}>

{/* prettier-ignore */}
```jsx
export default function EmojiSticker({ imageSize, stickerSource }) {
  // rest of the code

  return (
    /* @info Wrap all components inside PanGestureHandler. */<PanGestureHandler onGestureEvent={onDrag}>/* @end */
      /* @info Add containerStyle to the AnimatedView style prop. */<AnimatedView style={[containerStyle, { top: -350 }]}>/* @end */
        <TapGestureHandler onGestureEvent={onDoubleTap} numberOfTaps={2}>
          <AnimatedImage
            source={stickerSource}
            resizeMode="contain"
            style={[imageStyle, { width: imageSize, height: imageSize }]}
          />
        </TapGestureHandler>
      </AnimatedView>
    /* @info */</PanGestureHandler>/* @end */
  );
}
```

</SnackInline>

Let's take a look at our app on iOS, Android and the web:

<Video file="tutorial/pan-gesture.mp4" />

</Step>

## Next step

We successfully implemented pan and tap gestures.

<BoxLink
  title="Take a screenshot"
  Icon={BookOpen02Icon}
  description="In the next chapter, we'll learn how to take a screenshot of the image and the sticker, and save it on the device's library."
  href="/tutorial/screenshot"
/>