Animation and Gestures

Animation should explain change, preserve continuity, or confirm interaction. Keep continuous gesture and animation work off the JavaScript thread, and make the non-animated state correct before adding motion.

The examples target React Native Gesture Handler 3's hook API, such as usePanGesture. The older Gesture.Pan() builder belongs to the Gesture Handler 2 compatibility surface; migrate it before combining snippets from older projects with this guide.

For task-ready implementations, call get-react-native-guide({ topic: "react-native-animation-recipes" }). This guide explains the decisions; the recipe topic contains independently written press, swipe, scroll, accessibility, and reduced-motion code.

Pick the Right Mechanism

• Use layout or platform transitions for navigation and structural change when they already communicate the relationship.
• Use Reanimated shared values and worklets for per-frame transforms, opacity, and gesture-linked motion.
• Use Gesture Handler for recognition and composition of taps, pans, swipes, and simultaneous gestures.
• Use native tab and toolbar effects only where the platform supplies the intended behavior.

Animate transform and opacity when possible. Layout animation can be appropriate, but it costs more and must be measured on representative devices.

Design a Swipeable Interaction

1. Decide whether the gesture reveals actions, commits an action, or changes navigation.
2. Set a threshold based on intent, velocity, and distance rather than one magic distance.
3. Keep destructive actions reversible or require a clear second commitment.
4. Provide the same action without a gesture for accessibility and discoverability.
5. Resolve gesture conflicts with scrolling explicitly.

The visual position, action reveal, and haptic feedback should all agree on when the gesture crosses a commitment boundary.

Respect User and Platform Preferences

Honor reduced-motion settings. Shorten or remove decorative travel while retaining state feedback. Do not stack a custom transition over a native navigation transition unless the combined result has been tested for interruption, back gestures, and dropped frames.

Performance Checklist

• No React state update occurs on every gesture frame.
• Animated work reads stable shared values.
• Heavy shadows, blur, and large translucent layers are measured on low-end Android devices.
• Animations can be interrupted and reversed without jumping.
• Lists do not mount expensive animated children outside the viewport.

Start from a Gesture Baseline

This example uses the public Reanimated and Gesture Handler APIs to create an interruptible horizontal drag that coexists with vertical scrolling.

import type { ReactNode } from "react";
import { GestureDetector, usePanGesture } from "react-native-gesture-handler";
import Animated, {
  ReduceMotion,
  useAnimatedStyle,
  useSharedValue,
  withSpring,
} from "react-native-reanimated";

const returnSpring = {
  damping: 24,
  stiffness: 280,
  overshootClamping: true,
  reduceMotion: ReduceMotion.System,
} as const;

export function DraggableCard({ children }: { children: ReactNode }) {
  const translateX = useSharedValue(0);

  const pan = usePanGesture({
    activeOffsetX: [-8, 8],
    failOffsetY: [-12, 12],
    onUpdate: (event) => {
      translateX.set(event.translationX);
    },
    onFinalize: () => {
      translateX.set(withSpring(0, returnSpring));
    },
  });

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

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={animatedStyle}>{children}</Animated.View>
    </GestureDetector>
  );
}

Activation and failure offsets help this horizontal gesture coexist with a vertical list. ReduceMotion.System follows the device preference, shared-value get/set works with the React Compiler, and the finalizer returns the card after completion or cancellation. If the drag commits an action, expose the same action through an accessible button and clamp or threshold the gesture from measured layout rather than hard-coded screen coordinates.

Sources

API details are checked against the official Reanimated shared-value, Reanimated spring, Reanimated reduced-motion, Gesture Handler 3 pan, and Gesture Handler 3 migration documentation.