React Native (Expo) animations — Reanimated v4 + Gesture Handler

Defaults (pick these unless there’s a reason not to)

1. Simple state change (hover/pressed/toggled, small style changes): use Reanimated CSS Transitions.
2. Mount/unmount + layout changes (lists, accordions, reflow): use Reanimated Layout Animations.
3. Interactive / per-frame (gestures, scroll, physics, drag): use Shared Values + worklets (UI thread).

Quick start

Install (Expo)

npx expo install react-native-reanimated react-native-worklets react-native-gesture-handler

node {baseDir}/scripts/check-setup.mjs

1) Shared value +

withTiming

import { Pressable } from 'react-native';
import Animated, { useSharedValue, useAnimatedStyle, withTiming } from 'react-native-reanimated';

export function FadeInBox() {
  const opacity = useSharedValue(0);

  const style = useAnimatedStyle(() => ({ opacity: opacity.value }));

  return (
    <Pressable onPress={() => (opacity.value = withTiming(opacity.value ? 0 : 1, { duration: 200 }))}>
      <Animated.View style={[{ width: 80, height: 80 }, style]} />
    </Pressable>
  );
}

2) Pan gesture driving translation (UI thread)

import Animated, { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';
import { GestureDetector, usePanGesture } from 'react-native-gesture-handler';

export function Draggable() {
  const x = useSharedValue(0);
  const y = useSharedValue(0);

  const pan = usePanGesture({
    onUpdate: (e) => {
      x.value = e.translationX;
      y.value = e.translationY;
    },
    onDeactivate: () => {
      x.value = withSpring(0);
      y.value = withSpring(0);
    },
  });

  const style = useAnimatedStyle(() => ({ transform: [{ translateX: x.value }, { translateY: y.value }] }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[{ width: 100, height: 100 }, style]} />
    </GestureDetector>
  );
}

3) CSS-style transition (best for “style changes when state changes”)

import Animated from 'react-native-reanimated';

export function ExpandingCard({ expanded }: { expanded: boolean }) {
  return (
    <Animated.View
      style={{
        width: expanded ? 260 : 180,
        transitionProperty: 'width',
        transitionDuration: 220,
      }}
    />
  );
}

Workflow (copy this and tick it off)

• Identify the driver: state, layout, gesture, or scroll.
• Choose the primitive:
  • state → CSS transition / CSS animation
  • layout/mount → entering/exiting/layout transitions
  • gesture/scroll → shared values + worklets
• Keep per-frame work on the UI thread (worklets); avoid React state updates every frame.
• If a JS-side effect is required (navigation, analytics, state set), call it via

  scheduleOnRN

  .
• Verify on-device (Hermes inspector), not “Remote JS Debugging”.

Core patterns

Shared values are the “wire format” between runtimes

• Use

  useSharedValue

  for numbers/strings/objects that must be read/written from both UI and JS.
• Derive styles with

  useAnimatedStyle

  .
• Prefer

  withTiming

  for UI tweens;

  withSpring

  for physics.

UI thread vs JS thread: the only rule that matters

• Gesture callbacks and animated styles should stay workletized (UI runtime).
• Only bridge to JS when you must (via

  scheduleOnRN

  ).

Gesture Handler: use one API style per subtree

• Default to hook API (

  usePanGesture

  ,

  useTapGesture

  , etc.).
• Do not nest GestureDetectors that use different API styles (hook vs builder).
• Do not reuse the same gesture instance across multiple detectors.

CSS Transitions (Reanimated 4)

• Always set

  transitionProperty

  +

  transitionDuration

  .
• Avoid

  transitionProperty: 'all'

  (perf + surprise animations).
• Discrete properties (e.g.

  flexDirection

  ) won’t transition smoothly; use Layout Animations instead.

Layout animations

Scroll-linked animations

• references/recipes.md

Troubleshooting checklist

1. “Failed to create a worklet” / worklet not running

• Ensure the correct Babel plugin is configured for your environment.
  • Expo: handled by

    babel-preset-expo

    when installed via

    expo install

    .
  • Bare RN: Reanimated 4 uses

    react-native-worklets/plugin

    .

1. Gesture callbacks not firing / weird conflicts

• Ensure the app root is wrapped with

  GestureHandlerRootView

  .
• Don’t reuse gestures across detectors; don’t mix hook and builder API in nested detectors.

1. Needing to call JS from a worklet

• Use

  scheduleOnRN(fn, ...args)

  .

• fn

  must be defined in JS scope (component body or module scope), not created inside a worklet.

1. Jank / dropped frames

• Check for large objects captured into worklets; capture primitives instead.
• Avoid

  transitionProperty: 'all'

  .
• Don’t set React state every frame.

Bundled references (open only when needed)

• references/setup-and-compat.md: Expo vs bare setup, New Architecture requirement, common incompatibilities.
• references/worklets-and-threading.md: UI runtime,

  scheduleOnUI

  /

  scheduleOnRN

  , closure capture, migration notes.
• references/gestures.md: GestureDetector, hook API patterns, composition, gotchas.
• references/css-transitions-and-animations.md: Reanimated 4 CSS transitions/animations quick reference.
• references/layout-animations.md: entering/exiting/layout transitions and how to pick.
• references/recipes.md: copy-paste components (drag, swipe, pinch, bottom sheet-ish, scroll effects).
• references/debugging-and-performance.md: diagnosing worklet issues, profiling, common perf traps.

Quick search

grep -Rni "scheduleOnRN" {baseDir}/references
grep -Rni "transitionProperty" {baseDir}/references
grep -Rni "usePanGesture" {baseDir}/references

Primary docs

• Reanimated (v4): https://docs.swmansion.com/react-native-reanimated/
• Gesture Handler (latest): https://docs.swmansion.com/react-native-gesture-handler/
• Expo Reanimated: https://docs.expo.dev/versions/latest/sdk/reanimated/
• Expo Gesture Handler: https://docs.expo.dev/versions/latest/sdk/gesture-handler/