/mobile-animation-reanimated

name: mobile-animation-reanimated
description: React Native Reanimated 4 - shared values, animated styles, spring/timing/decay, layout animations, gesture integration, scroll-driven animations, interpolation, worklets, CSS animations

React Native Reanimated Patterns

> **Quick Guide:** Reanimated 4 is New Architecture only (requires `react-native-worklets` as a separate dependency). Use `useSharedValue` + `useAnimatedStyle` for all animations. Animations run on the UI thread via worklets -- never block the JS thread. Use `withSpring` (physics-based) or `withTiming` (duration-based) for transitions, layout animations (`entering`/`exiting`) for mount/unmount, and `useScrollOffset` (renamed from `useScrollViewOffset`) for scroll-driven animations. Reanimated 4 also introduces CSS animations/transitions as a declarative alternative to the worklet API.

---

<critical_requirements>

CRITICAL: Before Using This Skill

**(You MUST use Animated components (`Animated.View`, `Animated.Text`, etc.) for any animated styles -- passing animated styles to regular components causes errors)**

**(You MUST keep static styles in `StyleSheet.create` and only animate dynamic properties in `useAnimatedStyle` -- animating static values wastes UI thread resources)**

**(You MUST NOT mutate shared values inside `useAnimatedStyle` callbacks -- read only, or you cause infinite loops)**

**(You MUST use `react-native-worklets` as a separate dependency in Reanimated 4 -- the worklet Babel plugin moved from `react-native-reanimated/plugin` to `react-native-worklets/plugin`)**

</critical_requirements>

---

**Auto-detection:** Reanimated, react-native-reanimated, useSharedValue, useAnimatedStyle, withSpring, withTiming, withDecay, Animated.View, Animated.Text, Animated.ScrollView, entering, exiting, FadeIn, FadeOut, SlideIn, interpolate, interpolateColor, useScrollOffset, GestureDetector, Gesture.Pan, worklet, layout animation, shared value, energyThreshold, CSS animation, react-native-worklets

**When to use:**

• Animating view properties (opacity, transforms, colors) on the UI thread
• Adding entering/exiting animations when components mount/unmount
• Building gesture-driven animations (drag, swipe, pinch)
• Creating scroll-driven header collapse, parallax, or sticky effects
• Interpolating values across ranges (position to opacity, scroll to scale)
• Implementing spring physics or timing-based transitions

**When NOT to use:**

• Simple boolean show/hide without animation (conditional rendering suffices)
• Static layouts that never change at runtime
• Animated.Value from React Native core (use Reanimated's shared values instead)

**Key patterns covered:**

• Shared values (`useSharedValue`) + animated styles (`useAnimatedStyle`)
• Animation functions: `withTiming`, `withSpring`, `withDecay`
• Layout animations: `entering`/`exiting` with predefined builders
• Gesture integration: `Gesture.Pan` + shared values + `withDecay`
• Scroll-driven animations with `useScrollOffset`
• Interpolation: `interpolate` and `interpolateColor`
• Worklet functions and the `'worklet'` directive
• CSS animations and transitions (Reanimated 4 declarative API)

**Detailed Resources:**

• [examples/core.md](examples/core.md) - Shared values, animated styles, withTiming, withSpring, interpolation
• [examples/layout-animations.md](examples/layout-animations.md) - Entering/exiting animations, predefined builders, custom layout animations
• [examples/gestures.md](examples/gestures.md) - Pan gesture with shared values, swipe-to-dismiss, withDecay
• [examples/scroll-animations.md](examples/scroll-animations.md) - Collapsing header, parallax, scroll-driven opacity
• [reference.md](reference.md) - Decision frameworks, migration from 3.x, API quick reference

---

<philosophy>

Philosophy

Reanimated runs animations on the **UI thread** via worklets, keeping the JS thread free for business logic. The core model: **shared values** are reactive state that bridges JS and UI threads, **animated styles** derive visual properties from shared values, and **animation functions** (`withSpring`, `withTiming`, `withDecay`) drive transitions between values.

**Reanimated 4 key changes from 3.x:**

• **New Architecture only** -- drops Legacy Architecture (bridge) support entirely
• **`react-native-worklets`** as a separate package -- Babel plugin moved from `react-native-reanimated/plugin` to `react-native-worklets/plugin`
• **CSS animations/transitions** -- declarative API for state-driven animations (use CSS for simple state transitions, worklets for gesture/scroll-driven)
• **`energyThreshold`** replaces `restDisplacementThreshold`/`restSpeedThreshold` in `withSpring`
• **`useScrollOffset`** replaces `useScrollViewOffset` (deprecated alias remains)
• **Threading functions moved** to `react-native-worklets`: `runOnJS` -> `scheduleOnRN`, `runOnUI` -> `scheduleOnUI`

**When to use CSS animations vs worklets:**

• **CSS animations/transitions** -- state-driven, declarative, less code, better optimizable by Reanimated
• **Worklets** -- gesture-driven, scroll-driven, complex orchestration, frame-by-frame control

**Backward compatibility:** All v2/v3 shared value and animation APIs work unchanged in v4. CSS animations and worklet-based animations work simultaneously and interchangeably.

</philosophy>

---

<patterns>

Core Patterns

Pattern 1: Shared Values and Animated Styles

The fundamental building blocks. `useSharedValue` creates reactive state on the UI thread. `useAnimatedStyle` derives styles that update when shared values change.

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

const EXPANDED_HEIGHT = 200;
const COLLAPSED_HEIGHT = 60;
const ANIMATION_DURATION = 300;

function CollapsibleCard() {
  const height = useSharedValue(COLLAPSED_HEIGHT);

  const animatedStyle = useAnimatedStyle(() => ({
    height: height.value,
  }));

  const toggle = () => {
    h