# Reanimated - Core Patterns

> Shared values, animated styles, animation functions, and interpolation. See [SKILL.md](../SKILL.md) for decision guidance and red flags.

**Prerequisites:** Reanimated 4 installed with `react-native-worklets`. New Architecture enabled (React Native 0.76+).

---

## Pattern 1: Shared Value + Animated Style Basics

```typescript
import { useState } from "react";
import { Pressable, Text, StyleSheet } from "react-native";
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withTiming,
} from "react-native-reanimated";

const BOX_SIZE = 100;
const SCALE_ACTIVE = 1.2;
const SCALE_INACTIVE = 1;
const OPACITY_ACTIVE = 1;
const OPACITY_INACTIVE = 0.5;
const ANIMATION_DURATION = 300;

export function AnimatedBox() {
  const [active, setActive] = useState(false);
  const scale = useSharedValue(SCALE_INACTIVE);
  const opacity = useSharedValue(OPACITY_INACTIVE);

  // Only dynamic properties in useAnimatedStyle
  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ scale: scale.value }],
    opacity: opacity.value,
  }));

  const handlePress = () => {
    const nextActive = !active;
    setActive(nextActive);
    scale.value = withTiming(
      nextActive ? SCALE_ACTIVE : SCALE_INACTIVE,
      { duration: ANIMATION_DURATION }
    );
    opacity.value = withTiming(
      nextActive ? OPACITY_ACTIVE : OPACITY_INACTIVE,
      { duration: ANIMATION_DURATION }
    );
  };

  return (
    <Pressable onPress={handlePress}>
      {/* Static styles in StyleSheet, dynamic in animatedStyle */}
      <Animated.View style={[styles.box, animatedStyle]}>
        <Text>{active ? "Active" : "Inactive"}</Text>
      </Animated.View>
    </Pressable>
  );
}

const styles = StyleSheet.create({
  box: {
    width: BOX_SIZE,
    height: BOX_SIZE,
    backgroundColor: "#3498db",
    borderRadius: 8,
    alignItems: "center",
    justifyContent: "center",
  },
});
```

**Why good:** static styles (width, height, backgroundColor, borderRadius) stay in StyleSheet, only dynamic properties (scale, opacity) in useAnimatedStyle, named constants for all values

---

## Pattern 2: React Compiler Compatibility

When using React Compiler, use `get()` and `set()` instead of direct `.value` access to avoid the compiler misinterpreting shared value reactivity.

```typescript
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
} from "react-native-reanimated";

const TARGET_POSITION = 200;
const INITIAL_POSITION = 0;

export function CompilerSafeAnimation() {
  const translateX = useSharedValue(INITIAL_POSITION);

  // get() instead of .value in animated style
  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ translateX: translateX.get() }],
  }));

  const handlePress = () => {
    // set() with updater function instead of .value assignment
    translateX.set((current) =>
      current === INITIAL_POSITION ? TARGET_POSITION : INITIAL_POSITION
    );
  };

  return (
    <Pressable onPress={handlePress}>
      <Animated.View style={[styles.box, animatedStyle]} />
    </Pressable>
  );
}
```

**Why good:** `get()`/`set()` are React Compiler safe -- direct `.value` access may be misinterpreted by the compiler's memoization analysis

**When to use:** only when your project uses React Compiler. Direct `.value` access remains valid without the compiler.

---

## Pattern 3: withSpring Configuration

Two modes: physics-based (damping/stiffness) and duration-based (duration/dampingRatio). Don't mix parameters from both modes.

```typescript
import { useSharedValue, withSpring } from "react-native-reanimated";

const TARGET = 100;

// Physics-based: natural feel, bouncy
// Lower damping = more bouncy, higher stiffness = snappier
function physicsSpring(sv: ReturnType<typeof useSharedValue<number>>) {
  sv.value = withSpring(TARGET, {
    damping: 80, // how quickly it settles (default: 120)
    stiffness: 600, // how bouncy (default: 900)
    mass: 1, // weight (default: 4)
  });
}

// Duration-based: predictable timing with spring feel
// dampingRatio < 1 = bouncy, 1 = critically damped (no overshoot), > 1 = overdamped
function durationSpring(sv: ReturnType<typeof useSharedValue<number>>) {
  sv.value = withSpring(TARGET, {
    duration: 400, // perceptual duration in ms (default: 550)
    dampingRatio: 0.7, // < 1 bouncy, 1 no bounce, > 1 overdamped
  });
}

// Clamped spring: prevents overshoot past boundaries
function clampedSpring(sv: ReturnType<typeof useSharedValue<number>>) {
  sv.value = withSpring(TARGET, {
    duration: 400,
    dampingRatio: 0.7,
    clamp: { min: 0, max: 120 }, // limits movement range
  });
}

// With completion callback
function springWithCallback(sv: ReturnType<typeof useSharedValue<number>>) {
  sv.value = withSpring(TARGET, { damping: 100 }, (finished) => {
    "worklet";
    if (finished) {
      // Animation completed -- safe to trigger next animation
    }
  });
}
```

**Why good:** clear separation of physics-based vs duration-based configs, clamp prevents visual overshoot, callback for chaining

**Migration note:** `restDisplacementThreshold` and `restSpeedThreshold` are removed in v4. The new `energyThreshold` (default `6e-9`) is relative to the animation. In most cases, just delete the old threshold parameters.

---

## Pattern 4: withTiming and Easing

```typescript
import {
  withTiming,
  Easing,
  withSequence,
  withRepeat,
  withDelay,
} from "react-native-reanimated";

const ANIMATION_DURATION = 300;
const FADE_DELAY = 200;
const SHAKE_OFFSET = 10;
const SHAKE_DURATION = 80;
const SHAKE_REPETITIONS = 3;

// Basic timing with easing
function fadeIn(sv: SharedValue<number>) {
  sv.value = withTiming(1, {
    duration: ANIMATION_DURATION,
    easing: Easing.bezierFn(0.25, 0.1, 0.25, 1),
  });
}

// Delayed animation
function delayedFade(sv: SharedValue<number>) {
  sv.value = withDelay(
    FADE_DELAY,
    withTiming(1, { duration: ANIMATION_DURATION }),
  );
}

// Sequence: shake animation
function shake(sv: SharedValue<number>) {
  sv.value = withSequence(
    withTiming(-SHAKE_OFFSET, { duration: SHAKE_DURATION }),
    withRepeat(
      withTiming(SHAKE_OFFSET, { duration: SHAKE_DURATION }),
      SHAKE_REPETITIONS,
      true, // reverse each iteration
    ),
    withTiming(0, { duration: SHAKE_DURATION }),
  );
}
```

**Easing presets:** `Easing.linear`, `Easing.ease`, `Easing.quad`, `Easing.cubic`, `Easing.bezierFn(x1, y1, x2, y2)`, `Easing.inOut(Easing.quad)`, `Easing.in(Easing.elastic(1))`, `Easing.out(Easing.bounce)`.

---

## Pattern 5: withDecay (Momentum)

Simulates friction-based deceleration. Commonly used after gesture fling to maintain momentum.

```typescript
import { withDecay, withClamp } from "react-native-reanimated";

const MIN_POSITION = 0;
const MAX_POSITION = 300;

// Basic decay with velocity from gesture
function applyDecay(sv: SharedValue<number>, velocity: number) {
  sv.value = withDecay({
    velocity,
    rubberBandEffect: true, // bounces at edges instead of hard stop
    clamp: [MIN_POSITION, MAX_POSITION], // boundaries
  });
}

// Alternative: withClamp modifier wrapping other animations
function clampedDecay(sv: SharedValue<number>, velocity: number) {
  sv.value = withClamp(
    { min: MIN_POSITION, max: MAX_POSITION },
    withDecay({ velocity }),
  );
}
```

**Why good:** `rubberBandEffect` gives iOS-like elastic boundary behavior, `clamp` prevents values escaping range

---

## Pattern 6: Interpolation

Map value ranges. Use in `useAnimatedStyle` for scroll-driven or gesture-driven transformations.

```typescript
import {
  interpolate,
  interpolateColor,
  Extrapolation,
  useAnimatedStyle,
} from "react-native-reanimated";

const SCROLL_THRESHOLD = 100;
const HEADER_MAX = 200;
const HEADER_MIN = 60;

// Number interpolation with clamping
function useHeaderStyle(scrollY: SharedValue<number>) {
  return useAnimatedStyle(() => {
    const height = interpolate(
      scrollY.value,
      [0, HEADER_MAX - HEADER_MIN],
      [HEADER_MAX, HEADER_MIN],
      Extrapolation.CLAMP,
    );
    const opacity = interpolate(
      scrollY.value,
      [0, SCROLL_THRESHOLD],
      [1, 0],
      Extrapolation.CLAMP,
    );
    return { height, opacity };
  });
}

// Color interpolation: progress bar changes color
function useProgressColor(progress: SharedValue<number>) {
  return useAnimatedStyle(() => {
    const backgroundColor = interpolateColor(
      progress.value,
      [0, 0.5, 1],
      ["#FF3B30", "#FFCC00", "#34C759"], // red -> yellow -> green
    );
    return { backgroundColor };
  });
}

// Mixed left/right extrapolation
function useParallax(scrollY: SharedValue<number>) {
  return useAnimatedStyle(() => {
    const translateY = interpolate(
      scrollY.value,
      [0, SCROLL_THRESHOLD],
      [0, -50],
      {
        extrapolateLeft: Extrapolation.CLAMP, // don't go past 0
        extrapolateRight: Extrapolation.EXTEND, // continue beyond range
      },
    );
    return { transform: [{ translateY }] };
  });
}
```

**Extrapolation types:**

| Type       | Behavior                      |
| ---------- | ----------------------------- |
| `CLAMP`    | Caps output at range edges    |
| `EXTEND`   | Continues linearly past range |
| `IDENTITY` | Returns the raw input value   |

**`interpolateColor` modes:** `'RGB'` (default) or `'HSV'`. HSV produces perceptually smoother hue transitions (e.g., red to blue through purple, not through muddy brown).

---

## Pattern 7: Animated Text and Animated.createAnimatedComponent

Not all components have `Animated.*` wrappers. Use `Animated.createAnimatedComponent` for custom components.

```typescript
import Animated from "react-native-reanimated";
import { TextInput } from "react-native";

// Built-in: Animated.View, Animated.Text, Animated.ScrollView, Animated.Image, Animated.FlatList
// Custom: wrap any component that accepts style prop
const AnimatedTextInput = Animated.createAnimatedComponent(TextInput);

// Usage
function AnimatedSearch() {
  const width = useSharedValue(200);

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

  return <AnimatedTextInput style={[styles.input, style]} placeholder="Search..." />;
}
```

**Why good:** extends Reanimated to any component that accepts a `style` prop, type-safe with the wrapped component's props

**Gotcha:** `createAnimatedComponent` should be called at module level, not inside a component -- calling it in render creates a new component type each time, breaking React reconciliation.

# Reanimated - Gesture Integration

> Gesture-driven animations using react-native-gesture-handler + Reanimated shared values. See [SKILL.md](../SKILL.md) for decision guidance.

**Related:** [core.md](core.md) for shared values and withDecay.

**Note:** This file covers Reanimated's side of gesture-driven animations. For gesture configuration details (tap, pinch, fling, simultaneous/exclusive gestures), see the gesture handler skill.

---

## Pattern 1: Draggable Element with Pan Gesture

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

const INITIAL_POSITION = 0;

export function DraggableCircle() {
  const translateX = useSharedValue(INITIAL_POSITION);
  const translateY = useSharedValue(INITIAL_POSITION);
  const savedX = useSharedValue(INITIAL_POSITION);
  const savedY = useSharedValue(INITIAL_POSITION);

  const pan = Gesture.Pan()
    .onStart(() => {
      // Save position at gesture start for relative movement
      savedX.value = translateX.value;
      savedY.value = translateY.value;
    })
    .onUpdate((e) => {
      // Absolute translation from gesture start
      translateX.value = savedX.value + e.translationX;
      translateY.value = savedY.value + e.translationY;
    })
    .onEnd(() => {
      // Spring back to origin
      translateX.value = withSpring(INITIAL_POSITION);
      translateY.value = withSpring(INITIAL_POSITION);
    });

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

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

const styles = StyleSheet.create({
  circle: {
    width: 80,
    height: 80,
    borderRadius: 40,
    backgroundColor: "#3498db",
  },
});
```

**Why good:** `onStart` saves position for relative movement, `onUpdate` uses absolute translationX/Y from gesture start, `onEnd` springs back, gesture callbacks are auto-workletized

### onUpdate vs onChange

- **`onUpdate`** -- receives absolute values (`translationX`, `translationY`) relative to gesture start
- **`onChange`** -- receives delta values (`changeX`, `changeY`) since last event

Use `onChange` when accumulating position incrementally. Use `onUpdate` when setting position from a known start point.

---

## Pattern 2: Swipe-to-Dismiss

```typescript
import { Dimensions, StyleSheet, Text } from "react-native";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withTiming,
  interpolate,
  Extrapolation,
  type SharedValue,
} from "react-native-reanimated";
import { scheduleOnRN } from "react-native-worklets";

const SCREEN_WIDTH = Dimensions.get("window").width;
const DISMISS_THRESHOLD = SCREEN_WIDTH * 0.3;
const DISMISS_VELOCITY = 500;
const ANIMATION_DURATION = 200;

interface SwipeableCardProps {
  onDismiss: () => void;
  children: React.ReactNode;
}

export function SwipeableCard({ onDismiss, children }: SwipeableCardProps) {
  const translateX = useSharedValue(0);

  const pan = Gesture.Pan()
    .activeOffsetX([-10, 10])  // require 10px horizontal movement to activate
    .onChange((e) => {
      translateX.value += e.changeX;
    })
    .onFinalize((e) => {
      const shouldDismiss =
        Math.abs(translateX.value) > DISMISS_THRESHOLD ||
        Math.abs(e.velocityX) > DISMISS_VELOCITY;

      if (shouldDismiss) {
        const direction = translateX.value > 0 ? 1 : -1;
        translateX.value = withTiming(
          direction * SCREEN_WIDTH,
          { duration: ANIMATION_DURATION },
          () => {
            // scheduleOnRN to call JS function from UI thread
            scheduleOnRN(onDismiss);
          }
        );
      } else {
        // Snap back
        translateX.value = withTiming(0, { duration: ANIMATION_DURATION });
      }
    });

  const animatedStyle = useAnimatedStyle(() => ({
    transform: [{ translateX: translateX.value }],
    opacity: interpolate(
      Math.abs(translateX.value),
      [0, SCREEN_WIDTH],
      [1, 0.5],
      Extrapolation.CLAMP
    ),
  }));

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[styles.card, animatedStyle]}>
        {children}
      </Animated.View>
    </GestureDetector>
  );
}

const styles = StyleSheet.create({
  card: {
    padding: 16,
    backgroundColor: "#FFFFFF",
    borderRadius: 12,
    shadowColor: "#000",
    shadowOffset: { width: 0, height: 2 },
    shadowOpacity: 0.1,
    shadowRadius: 4,
    elevation: 3,
  },
});
```

**Why good:** `activeOffsetX` prevents accidental activation during vertical scroll, velocity check catches fast flicks, `scheduleOnRN` bridges from UI thread callback to JS, opacity fades with distance

**Key points:**

- `scheduleOnRN` (Reanimated 4) replaces `runOnJS` for calling JS functions from worklets
- `onFinalize` fires when gesture ends regardless of success/failure -- safer than `onEnd` for cleanup
- `activeOffsetX` with symmetric values prevents horizontal pan from stealing vertical scroll

---

## Pattern 3: Gesture with Decay (Fling Momentum)

```typescript
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withDecay,
} from "react-native-reanimated";

const MIN_X = 0;
const MAX_X = 300;

export function FlickableElement() {
  const offsetX = useSharedValue(0);

  const pan = Gesture.Pan()
    .onChange((e) => {
      offsetX.value += e.changeX;
    })
    .onFinalize((e) => {
      // withDecay preserves momentum from the fling
      offsetX.value = withDecay({
        velocity: e.velocityX,
        rubberBandEffect: true,    // elastic bounce at boundaries
        clamp: [MIN_X, MAX_X],    // movement boundaries
      });
    });

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

  return (
    <GestureDetector gesture={pan}>
      <Animated.View style={[styles.element, animatedStyle]} />
    </GestureDetector>
  );
}
```

**Why good:** `withDecay` takes velocity directly from gesture event, `rubberBandEffect` gives iOS-like elastic boundary, `clamp` prevents element from escaping bounds

---

## Pattern 4: Scale on Press (Tap Gesture)

```typescript
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import Animated, {
  useSharedValue,
  useAnimatedStyle,
  withSpring,
} from "react-native-reanimated";

const SCALE_PRESSED = 0.95;
const SCALE_DEFAULT = 1;

export function PressableCard({ children }: { children: React.ReactNode }) {
  const scale = useSharedValue(SCALE_DEFAULT);

  const tap = Gesture.Tap()
    .onBegin(() => {
      scale.value = withSpring(SCALE_PRESSED, { damping: 100, stiffness: 800 });
    })
    .onFinalize(() => {
      scale.value = withSpring(SCALE_DEFAULT, { damping: 100, stiffness: 800 });
    });

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

  return (
    <GestureDetector gesture={tap}>
      <Animated.View style={[styles.card, animatedStyle]}>
        {children}
      </Animated.View>
    </GestureDetector>
  );
}
```

**Why good:** `onBegin` fires immediately on touch (not on release), `onFinalize` restores scale whether tap completes or cancels, spring gives natural bounce feel

# Reanimated - Layout Animations

> Entering/exiting animations, predefined builders, custom animations. See [SKILL.md](../SKILL.md) for decision guidance.

**Related:** [core.md](core.md) for shared values and animation functions.

---

## Pattern 1: Predefined Entering/Exiting

Apply to `Animated.*` components. Component must be conditionally rendered (mount/unmount triggers the animation).

```typescript
import { useState } from "react";
import { Pressable, Text, StyleSheet, View } from "react-native";
import Animated, {
  FadeIn,
  FadeOut,
  SlideInRight,
  SlideOutLeft,
  ZoomIn,
  BounceIn,
} from "react-native-reanimated";

const ANIMATION_DURATION = 400;
const STAGGER_DELAY = 100;

export function NotificationList({ items }: { items: Notification[] }) {
  return (
    <View style={styles.list}>
      {items.map((item, index) => (
        <Animated.View
          key={item.id}
          entering={SlideInRight.delay(index * STAGGER_DELAY).duration(ANIMATION_DURATION)}
          exiting={SlideOutLeft.duration(ANIMATION_DURATION)}
          style={styles.item}
        >
          <Text>{item.message}</Text>
        </Animated.View>
      ))}
    </View>
  );
}

const styles = StyleSheet.create({
  list: { gap: 8 },
  item: {
    padding: 16,
    backgroundColor: "#F0F0F0",
    borderRadius: 8,
  },
});
```

**Why good:** staggered delay based on index creates cascade effect, separate entering/exiting animations for different UX feel

### Available Builder Families

| Family     | Entering            | Exiting              | Variants                                |
| ---------- | ------------------- | -------------------- | --------------------------------------- |
| Fade       | `FadeIn`            | `FadeOut`            | Up, Down, Left, Right                   |
| Slide      | `SlideInRight`      | `SlideOutLeft`       | Up, Down, Left, Right                   |
| Zoom       | `ZoomIn`            | `ZoomOut`            | Up, Down, Left, Right, EasyUp, EasyDown |
| Bounce     | `BounceIn`          | `BounceOut`          | Up, Down, Left, Right                   |
| Flip       | `FlipInEasyX`       | `FlipOutEasyX`       | X, Y, XUp, XDown, YLeft, YRight         |
| LightSpeed | `LightSpeedInRight` | `LightSpeedOutRight` | Left, Right                             |
| Rotate     | `RotateInDownLeft`  | `RotateOutDownLeft`  | Up/Down + Left/Right                    |
| Pinwheel   | `PinwheelIn`        | `PinwheelOut`        | (no variants)                           |
| Roll       | `RollInLeft`        | `RollOutLeft`        | Left, Right                             |
| Stretch    | `StretchInX`        | `StretchOutX`        | X, Y                                    |

---

## Pattern 2: Modifier Chaining

Customize predefined animations with modifier methods.

```typescript
import Animated, { FadeIn, SlideInUp, BounceIn } from "react-native-reanimated";

const ENTER_DURATION = 500;
const EXIT_DURATION = 300;
const ENTER_DELAY = 200;

// Duration + easing
<Animated.View entering={FadeIn.duration(ENTER_DURATION).easing(Easing.bezierFn(0.25, 0.1, 0.25, 1))} />

// Spring-based (replaces default timing with spring physics)
<Animated.View entering={BounceIn.springify().damping(12).stiffness(200)} />

// Delay + callback
<Animated.View
  entering={SlideInUp.delay(ENTER_DELAY).withCallback((finished) => {
    "worklet";
    if (finished) {
      // Animation completed on UI thread
    }
  })}
/>

// Override initial values
<Animated.View
  entering={FadeIn.withInitialValues({ opacity: 0.3, transform: [{ scale: 0.8 }] })}
/>

// Accessibility: respect reduced motion preference
<Animated.View entering={FadeIn.reduceMotion(ReduceMotion.System)} />
```

**Performance tip:** Define builders outside the component or memoize them -- inline creation in JSX allocates new objects every render.

```typescript
// Good: defined once at module level
const ENTER_ANIMATION = FadeIn.duration(400).delay(100);
const EXIT_ANIMATION = FadeOut.duration(300);

function Card() {
  return <Animated.View entering={ENTER_ANIMATION} exiting={EXIT_ANIMATION} />;
}
```

---

## Pattern 3: EntryExitTransition (Replacing combineTransition)

`combineTransition` was removed in v4. Use `EntryExitTransition` to combine different entering and exiting animations into a single layout transition.

```typescript
import Animated, {
  FadeIn,
  FadeOut,
  SlideInRight,
  SlideOutLeft,
  EntryExitTransition,
} from "react-native-reanimated";

// Combine different entering and exiting animations
const LAYOUT_TRANSITION = EntryExitTransition
  .entering(SlideInRight)
  .exiting(FadeOut);

function AnimatedList({ items }: { items: Item[] }) {
  return (
    <View>
      {items.map((item) => (
        <Animated.View
          key={item.id}
          layout={LAYOUT_TRANSITION}
          style={styles.item}
        >
          <Text>{item.name}</Text>
        </Animated.View>
      ))}
    </View>
  );
}
```

---

## Pattern 4: Custom Entering/Exiting Animation

Build fully custom animations when predefined builders don't fit.

```typescript
import Animated, { withTiming, withSpring, type EntryAnimationsValues } from "react-native-reanimated";

const CUSTOM_DURATION = 600;
const INITIAL_OFFSET = 50;

// Custom entering animation function
function customEnteringAnimation(values: EntryAnimationsValues) {
  "worklet";
  const animations = {
    opacity: withTiming(1, { duration: CUSTOM_DURATION }),
    transform: [
      { translateY: withSpring(0, { damping: 100 }) },
      { scale: withSpring(1, { damping: 80 }) },
    ],
  };
  const initialValues = {
    opacity: 0,
    transform: [
      { translateY: INITIAL_OFFSET },
      { scale: 0.9 },
    ],
  };
  return { initialValues, animations };
}

function CustomAnimatedCard() {
  return (
    <Animated.View entering={customEnteringAnimation} style={styles.card}>
      <Text>Custom animation</Text>
    </Animated.View>
  );
}
```

**Why good:** full control over initial values and animation config per property, can mix spring and timing in one entering animation, `values` parameter provides target layout measurements (width, height, targetOriginX, etc.)

**Custom animation callback shape:**

- Receives `EntryAnimationsValues` (entering) or `ExitAnimationsValues` (exiting) with target layout info
- Must return `{ initialValues, animations }` where each has the same style property keys
- Must be marked with `'worklet'` directive

# Reanimated - Scroll-Driven Animations

> Scroll-driven animations with useScrollOffset, collapsing headers, parallax. See [SKILL.md](../SKILL.md) for decision guidance.

**Related:** [core.md](core.md) for interpolation patterns.

---

## Pattern 1: Collapsing Header

Track scroll offset and interpolate header height, title opacity, and background.

```typescript
import { StyleSheet, Text, View } from "react-native";
import Animated, {
  useAnimatedRef,
  useScrollOffset,
  useAnimatedStyle,
  interpolate,
  interpolateColor,
  Extrapolation,
} from "react-native-reanimated";

const HEADER_MAX_HEIGHT = 200;
const HEADER_MIN_HEIGHT = 60;
const SCROLL_DISTANCE = HEADER_MAX_HEIGHT - HEADER_MIN_HEIGHT;
const TITLE_FONT_MAX = 28;
const TITLE_FONT_MIN = 18;

export function CollapsibleHeaderScreen() {
  const scrollRef = useAnimatedRef<Animated.ScrollView>();
  const scrollOffset = useScrollOffset(scrollRef);

  const headerStyle = useAnimatedStyle(() => ({
    height: interpolate(
      scrollOffset.value,
      [0, SCROLL_DISTANCE],
      [HEADER_MAX_HEIGHT, HEADER_MIN_HEIGHT],
      Extrapolation.CLAMP
    ),
    backgroundColor: interpolateColor(
      scrollOffset.value,
      [0, SCROLL_DISTANCE],
      ["rgba(0,0,0,0)", "rgba(0,0,0,0.9)"]
    ),
  }));

  const titleStyle = useAnimatedStyle(() => ({
    fontSize: interpolate(
      scrollOffset.value,
      [0, SCROLL_DISTANCE],
      [TITLE_FONT_MAX, TITLE_FONT_MIN],
      Extrapolation.CLAMP
    ),
    opacity: interpolate(
      scrollOffset.value,
      [0, SCROLL_DISTANCE * 0.5, SCROLL_DISTANCE],
      [1, 0.8, 1],
      Extrapolation.CLAMP
    ),
  }));

  return (
    <View style={styles.container}>
      <Animated.View style={[styles.header, headerStyle]}>
        <Animated.Text style={[styles.title, titleStyle]}>
          Profile
        </Animated.Text>
      </Animated.View>

      <Animated.ScrollView
        ref={scrollRef}
        contentContainerStyle={{ paddingTop: HEADER_MAX_HEIGHT }}
        scrollEventThrottle={16}
      >
        {/* Scroll content */}
      </Animated.ScrollView>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  header: {
    position: "absolute",
    top: 0,
    left: 0,
    right: 0,
    zIndex: 1,
    justifyContent: "flex-end",
    paddingHorizontal: 16,
    paddingBottom: 12,
  },
  title: {
    color: "#FFFFFF",
    fontWeight: "bold",
  },
});
```

**Why good:** `useScrollOffset` auto-detects scroll direction, `Extrapolation.CLAMP` prevents over/under-shoot, font size and opacity give depth to the collapse

**Key detail:** `scrollEventThrottle={16}` is needed on `ScrollView` for smooth 60fps tracking. Without it, scroll events fire less frequently.

---

## Pattern 2: Parallax Image

Image moves at a slower rate than content, creating depth.

```typescript
import { StyleSheet, Text, View, Dimensions } from "react-native";
import Animated, {
  useAnimatedRef,
  useScrollOffset,
  useAnimatedStyle,
  interpolate,
  Extrapolation,
} from "react-native-reanimated";

const IMAGE_HEIGHT = 300;
const PARALLAX_FACTOR = 0.5;  // image moves at half the scroll speed

export function ParallaxScreen() {
  const scrollRef = useAnimatedRef<Animated.ScrollView>();
  const scrollOffset = useScrollOffset(scrollRef);

  const imageStyle = useAnimatedStyle(() => ({
    transform: [
      {
        translateY: interpolate(
          scrollOffset.value,
          [0, IMAGE_HEIGHT],
          [0, IMAGE_HEIGHT * PARALLAX_FACTOR],
          Extrapolation.CLAMP
        ),
      },
    ],
  }));

  const overlayStyle = useAnimatedStyle(() => ({
    opacity: interpolate(
      scrollOffset.value,
      [0, IMAGE_HEIGHT * 0.5],
      [0, 0.7],
      Extrapolation.CLAMP
    ),
  }));

  return (
    <Animated.ScrollView ref={scrollRef} scrollEventThrottle={16}>
      <View style={styles.imageContainer}>
        <Animated.Image
          source={{ uri: "https://example.com/hero.jpg" }}
          style={[styles.image, imageStyle]}
        />
        <Animated.View style={[styles.overlay, overlayStyle]} />
      </View>
      <View style={styles.content}>
        <Text>Content below parallax image</Text>
      </View>
    </Animated.ScrollView>
  );
}

const styles = StyleSheet.create({
  imageContainer: {
    height: IMAGE_HEIGHT,
    overflow: "hidden",
  },
  image: {
    width: "100%",
    height: IMAGE_HEIGHT * 1.5,  // taller than container for parallax room
  },
  overlay: {
    ...StyleSheet.absoluteFillObject,
    backgroundColor: "#000000",
  },
  content: {
    padding: 16,
    backgroundColor: "#FFFFFF",
  },
});
```

**Why good:** `PARALLAX_FACTOR` controls depth effect intensity, image is taller than container for scroll room, overlay fades in as image scrolls away

---

## Pattern 3: Scroll-to-Hide Tab Bar

Tab bar slides down and fades out when scrolling down, reappears when scrolling up.

```typescript
import { StyleSheet, View, Text } from "react-native";
import Animated, {
  useAnimatedRef,
  useScrollOffset,
  useSharedValue,
  useAnimatedStyle,
  withTiming,
  interpolate,
  Extrapolation,
} from "react-native-reanimated";

const TAB_BAR_HEIGHT = 60;
const SCROLL_THRESHOLD = 10;
const ANIMATION_DURATION = 200;

export function HidingTabBar() {
  const scrollRef = useAnimatedRef<Animated.ScrollView>();
  const scrollOffset = useScrollOffset(scrollRef);
  const prevOffset = useSharedValue(0);
  const tabBarTranslateY = useSharedValue(0);

  // Detect scroll direction and animate tab bar
  const animatedTabStyle = useAnimatedStyle(() => {
    const diff = scrollOffset.value - prevOffset.value;
    prevOffset.value = scrollOffset.value;

    if (diff > SCROLL_THRESHOLD) {
      // Scrolling down: hide
      tabBarTranslateY.value = withTiming(TAB_BAR_HEIGHT, {
        duration: ANIMATION_DURATION,
      });
    } else if (diff < -SCROLL_THRESHOLD) {
      // Scrolling up: show
      tabBarTranslateY.value = withTiming(0, {
        duration: ANIMATION_DURATION,
      });
    }

    return {
      transform: [{ translateY: tabBarTranslateY.value }],
      opacity: interpolate(
        tabBarTranslateY.value,
        [0, TAB_BAR_HEIGHT],
        [1, 0],
        Extrapolation.CLAMP
      ),
    };
  });

  return (
    <View style={styles.container}>
      <Animated.ScrollView ref={scrollRef} scrollEventThrottle={16}>
        {/* content */}
      </Animated.ScrollView>

      <Animated.View style={[styles.tabBar, animatedTabStyle]}>
        <Text>Tab 1</Text>
        <Text>Tab 2</Text>
        <Text>Tab 3</Text>
      </Animated.View>
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
  tabBar: {
    position: "absolute",
    bottom: 0,
    left: 0,
    right: 0,
    height: TAB_BAR_HEIGHT,
    flexDirection: "row",
    justifyContent: "space-around",
    alignItems: "center",
    backgroundColor: "#FFFFFF",
    borderTopWidth: 1,
    borderTopColor: "#E0E0E0",
  },
});
```

**Why good:** threshold prevents jittery show/hide on small scrolls, opacity interpolated from translateY for coordinated animation, previous offset tracked to detect direction