← Back to all posts

Mastering Pan Gestures with React Native Reanimated in Expo

In the world of React Native development, creating smooth and responsive gesture-based interactions can significantly enhance your app's user experience. One of the most common gestures users expect is the ability to pan or drag elements across the screen. In this guide, we'll dive deep into implementing pan gestures using React Native Reanimated with Expo - a combination that makes development faster and more accessible while still maintaining high-performance animations and gesture handling.

What You'll Learn

  • Setting up React Native Reanimated in your Expo project
  • Understanding the pan gesture handler
  • Creating basic pan gesture interactions
  • Advanced pan gesture techniques
  • Real-world examples and use cases

Prerequisites

  • Basic knowledge of React Native
  • Node.js and npm/yarn installed
  • Expo CLI installed (npm install -g expo-cli)

Setting Up React Native Reanimated in Expo

Before we start implementing pan gestures, we need to properly set up React Native Reanimated in our Expo project.

Creating a New Expo Project

# Create a new Expo project
expo init MyGestureApp
cd MyGestureApp

Installing Required Packages

# Install the required packages
expo install react-native-reanimated react-native-gesture-handler

# For complete gesture support also install
expo install react-native-screens @react-native-community/masked-view

Configuration

  1. Edit your babel.config.js to add the Reanimated plugin:
module.exports = function (api) {
  api.cache(true);
  return {
    presets: ["babel-preset-expo"],
    plugins: ["react-native-reanimated/plugin"],
  };
};
  1. In your App.js, import gesture handler at the top:
import "react-native-gesture-handler";
import React from "react";
import { StyleSheet, Text, View } from "react-native";

export default function App() {
  return (
    <View style={styles.container}>
      <Text>Let's start building with gestures!</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    backgroundColor: "#fff",
    alignItems: "center",
    justifyContent: "center",
  },
});

Understanding Pan Gesture Basics

A pan gesture occurs when a user touches the screen and moves their finger(s) in any direction. React Native Reanimated works with react-native-gesture-handler to provide a powerful system for handling these interactions.

Key Concepts

  1. Gesture Handler: Captures and interprets the user's touch input
  2. Worklets: JavaScript functions that run on the UI thread
  3. Shared Values: Values that can be accessed from both the JavaScript thread and the UI thread
  4. Animation Nodes: Define how values should be animated

Basic Pan Gesture Implementation

Let's start with a simple example: a box that follows your finger as you drag it around the screen.

import React from "react";
import { StyleSheet, View } from "react-native";
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withSpring,
} from "react-native-reanimated";
import { GestureDetector, Gesture } from "react-native-gesture-handler";

export default function BasicPanGesture() {
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);

  const panGesture = Gesture.Pan()
    .onUpdate((event) => {
      translateX.value = event.translationX;
      translateY.value = event.translationY;
    })
    .onEnd(() => {
      translateX.value = withSpring(0);
      translateY.value = withSpring(0);
    });

  const animatedStyle = useAnimatedStyle(() => {
    return {
      transform: [
        { translateX: translateX.value },
        { translateY: translateY.value },
      ],
    };
  });

  return (
    <View style={styles.container}>
      <GestureDetector gesture={panGesture}>
        <Animated.View style={[styles.box, animatedStyle]} />
      </GestureDetector>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
  },
  box: {
    width: 100,
    height: 100,
    backgroundColor: "blue",
    borderRadius: 10,
  },
});

Breaking Down the Code

  1. Shared Values: We create translateX and translateY shared values to track the position of our box.

  2. Pan Gesture: We define a pan gesture using Gesture.Pan().

    • onUpdate: Fires continuously as the user drags their finger
    • onEnd: Fires when the user lifts their finger

  3. Animated Style: We use useAnimatedStyle to create a style object that updates when our shared values change.

  4. GestureDetector: Wraps our animated component and connects it to the pan gesture.

Advanced Pan Gesture Techniques

Now that we understand the basics, let's explore some more advanced techniques.

Context and State Preservation

Often, you'll want to remember the previous position of your element when the user starts a new gesture. Here's how to do that:

import React from "react";
import { StyleSheet, View } from "react-native";
import Animated, {
  useAnimatedStyle,
  useSharedValue,
} from "react-native-reanimated";
import { GestureDetector, Gesture } from "react-native-gesture-handler";

export default function ContextPreservingPan() {
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);

  // Create context values to store the previous position
  const contextX = useSharedValue(0);
  const contextY = useSharedValue(0);

  const panGesture = Gesture.Pan()
    .onStart(() => {
      // Store starting values when gesture begins
      contextX.value = translateX.value;
      contextY.value = translateY.value;
    })
    .onUpdate((event) => {
      // Add the new translation to the previous position
      translateX.value = contextX.value + event.translationX;
      translateY.value = contextY.value + event.translationY;
    });

  const animatedStyle = useAnimatedStyle(() => {
    return {
      transform: [
        { translateX: translateX.value },
        { translateY: translateY.value },
      ],
    };
  });

  return (
    <View style={styles.container}>
      <GestureDetector gesture={panGesture}>
        <Animated.View style={[styles.box, animatedStyle]} />
      </GestureDetector>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
  },
  box: {
    width: 100,
    height: 100,
    backgroundColor: "blue",
    borderRadius: 10,
  },
});

Constraining Movement

You might want to restrict the movement of an element to a specific area or axis:

import React from "react";
import { StyleSheet, View, Dimensions } from "react-native";
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withDecay,
} from "react-native-reanimated";
import { GestureDetector, Gesture } from "react-native-gesture-handler";

const { width, height } = Dimensions.get("window");
const BOX_SIZE = 100;

export default function ConstrainedPanGesture() {
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);
  const contextX = useSharedValue(0);
  const contextY = useSharedValue(0);

  const panGesture = Gesture.Pan()
    .onStart(() => {
      contextX.value = translateX.value;
      contextY.value = translateY.value;
    })
    .onUpdate((event) => {
      // Calculate new positions
      let newX = contextX.value + event.translationX;
      let newY = contextY.value + event.translationY;

      // Constrain movement within screen bounds
      const maxX = (width - BOX_SIZE) / 2;
      const maxY = (height - BOX_SIZE) / 2;

      newX = Math.min(Math.max(newX, -maxX), maxX);
      newY = Math.min(Math.max(newY, -maxY), maxY);

      translateX.value = newX;
      translateY.value = newY;
    })
    .onEnd((event) => {
      // Add inertia with constraints
      const maxX = (width - BOX_SIZE) / 2;
      const maxY = (height - BOX_SIZE) / 2;

      translateX.value = withDecay({
        velocity: event.velocityX,
        clamp: [-maxX, maxX],
      });

      translateY.value = withDecay({
        velocity: event.velocityY,
        clamp: [-maxY, maxY],
      });
    });

  const animatedStyle = useAnimatedStyle(() => {
    return {
      transform: [
        { translateX: translateX.value },
        { translateY: translateY.value },
      ],
    };
  });

  return (
    <View style={styles.container}>
      <GestureDetector gesture={panGesture}>
        <Animated.View style={[styles.box, animatedStyle]} />
      </GestureDetector>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
  },
  box: {
    width: BOX_SIZE,
    height: BOX_SIZE,
    backgroundColor: "blue",
    borderRadius: 10,
  },
});

Real-World Example: Swipeable Card

Let's implement a common UI pattern: a swipeable card that can be dismissed.

import React from "react";
import { StyleSheet, View, Dimensions, Text } from "react-native";
import Animated, {
  useAnimatedStyle,
  useSharedValue,
  withSpring,
  runOnJS,
} from "react-native-reanimated";
import { GestureDetector, Gesture } from "react-native-gesture-handler";

const { width } = Dimensions.get("window");
const CARD_WIDTH = width * 0.8;
const SWIPE_THRESHOLD = width * 0.3;

export default function SwipeableCard() {
  const [cards, setCards] = React.useState([1, 2, 3, 4, 5]);
  const translateX = useSharedValue(0);
  const rotation = useSharedValue(0);

  const removeCard = React.useCallback(() => {
    setCards((prevCards) => prevCards.slice(1));
  }, []);

  const panGesture = Gesture.Pan()
    .onUpdate((event) => {
      translateX.value = event.translationX;
      // Rotate slightly as the card moves
      rotation.value = (event.translationX / width) * 20;
    })
    .onEnd((event) => {
      if (Math.abs(translateX.value) > SWIPE_THRESHOLD) {
        // Swiped far enough - dismiss the card
        const direction = translateX.value > 0 ? 1 : -1;
        translateX.value = withSpring(direction * width, {}, () => {
          runOnJS(removeCard)();
          translateX.value = 0;
          rotation.value = 0;
        });
      } else {
        // Not swiped far enough - return to center
        translateX.value = withSpring(0);
        rotation.value = withSpring(0);
      }
    });

  const animatedStyle = useAnimatedStyle(() => {
    return {
      transform: [
        { translateX: translateX.value },
        { rotate: `${rotation.value}deg` },
      ],
    };
  });

  if (cards.length === 0) {
    return (
      <View style={styles.container}>
        <Text>No more cards!</Text>
      </View>
    );
  }

  return (
    <View style={styles.container}>
      <GestureDetector gesture={panGesture}>
        <Animated.View style={[styles.card, animatedStyle]}>
          <Text style={styles.cardText}>{cards[0]}</Text>
        </Animated.View>
      </GestureDetector>

      {cards.length > 1 && (
        <View style={[styles.card, styles.nextCard]}>
          <Text style={styles.cardText}>{cards[1]}</Text>
        </View>
      )}
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
  },
  card: {
    width: CARD_WIDTH,
    height: CARD_WIDTH * 1.5,
    backgroundColor: "white",
    borderRadius: 10,
    justifyContent: "center",
    alignItems: "center",
    shadowColor: "#000",
    shadowOffset: {
      width: 0,
      height: 2,
    },
    shadowOpacity: 0.25,
    shadowRadius: 3.84,
    elevation: 5,
    position: "absolute",
  },
  nextCard: {
    top: 10,
    backgroundColor: "#f5f5f5",
    transform: [{ scale: 0.95 }],
  },
  cardText: {
    fontSize: 42,
    fontWeight: "bold",
  },
});

Combining Multiple Gestures

Reanimated allows you to combine multiple gestures. For example, you might want to allow both pan and pinch-zoom:

import React from "react";
import { StyleSheet, View } from "react-native";
import Animated, {
  useAnimatedStyle,
  useSharedValue,
} from "react-native-reanimated";
import { GestureDetector, Gesture } from "react-native-gesture-handler";

export default function MultiGestureComponent() {
  const translateX = useSharedValue(0);
  const translateY = useSharedValue(0);
  const scale = useSharedValue(1);

  const contextX = useSharedValue(0);
  const contextY = useSharedValue(0);
  const contextScale = useSharedValue(1);

  const panGesture = Gesture.Pan()
    .onStart(() => {
      contextX.value = translateX.value;
      contextY.value = translateY.value;
    })
    .onUpdate((event) => {
      translateX.value = contextX.value + event.translationX;
      translateY.value = contextY.value + event.translationY;
    });

  const pinchGesture = Gesture.Pinch()
    .onStart(() => {
      contextScale.value = scale.value;
    })
    .onUpdate((event) => {
      scale.value = contextScale.value * event.scale;
    });

  // Combine gestures
  const composedGesture = Gesture.Simultaneous(panGesture, pinchGesture);

  const animatedStyle = useAnimatedStyle(() => {
    return {
      transform: [
        { translateX: translateX.value },
        { translateY: translateY.value },
        { scale: scale.value },
      ],
    };
  });

  return (
    <View style={styles.container}>
      <GestureDetector gesture={composedGesture}>
        <Animated.View style={[styles.box, animatedStyle]} />
      </GestureDetector>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    justifyContent: "center",
    alignItems: "center",
  },
  box: {
    width: 150,
    height: 150,
    backgroundColor: "blue",
    borderRadius: 10,
  },
});

Performance Considerations

  1. Use Worklets: All your animations and gesture handlers should be using worklets (functions run on the UI thread).

  2. Avoid JS Thread Work: Minimize the work done on the JS thread during animations.

  3. Memoize Gestures: Use React's useMemo to memoize your gesture handlers.

  4. Layout Animations: For more complex layout changes, consider using Reanimated's layout animation capabilities.

Conclusion

Implementing pan gestures with React Native Reanimated opens up a whole new dimension of interactivity in your applications. From basic dragging to complex, multi-touch gestures, you now have the tools to create fluid, native-feeling interfaces that will delight your users.

Remember these key points:

  1. Use shared values to track the state of your gestures
  2. Leverage the gesture lifecycle methods (onStart, onUpdate, onEnd)
  3. Combine gestures for complex interactions
  4. Keep performance in mind

With these techniques in your toolkit, you're well-equipped to create engaging, gesture-driven interfaces in your React Native applications.

Additional Resources