Claude Skill

mobile-animation-reanimated

React Native Reanimated 4 - shared values, animated styles, spring/timing/decay, layout animations, gesture integration, scroll-driven animations, interpolation, worklets, CSS animations

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download agents-inc-skills-dist_plugins_mobile-animation-reanimated_skills_mobile-animation-reanimated-707467a.zip · 19 KB

Install

skills CLI npx skills add https://github.com/agents-inc/skills/tree/main/dist/plugins/mobile-animation-reanimated/skills/mobile-animation-reanimated
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install agents-inc-skills@llmmart
Git git clone https://github.com/agents-inc/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole agents-inc/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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:




<red_flags>

RED FLAGS

High Priority Issues:

  • Passing animated styles to regular View/Text instead of Animated.View/Animated.Text -- causes silent failure or crash
  • Mutating shared values inside useAnimatedStyle -- causes infinite re-evaluation loops
  • Using react-native-reanimated/plugin in Babel config with Reanimated 4 -- must use react-native-worklets/plugin (and it must be last in the plugins array)
  • Using Reanimated 4.x with Legacy Architecture (old bridge) -- Reanimated 4 is New Architecture only
  • Animating static properties in useAnimatedStyle instead of keeping them in StyleSheet -- wastes UI thread resources
  • Using restDisplacementThreshold/restSpeedThreshold in withSpring -- removed in v4, replaced by energyThreshold

Medium Priority Issues:

  • Creating layout animation builders inline in render -- allocates objects every render; define outside component or in useMemo
  • Using runOnJS/runOnUI instead of scheduleOnRN/scheduleOnUI -- old API moved to react-native-worklets
  • Missing GestureHandlerRootView at app root -- gestures silently fail without it
  • Using useAnimatedGestureHandler -- removed in v4, migrate to Gesture Handler 2's Gesture API

Gotchas and Edge Cases:

  • withSpring duration: actual completion time = perceptual duration x 1.5 -- divide v3 duration values by 1.5 when migrating
  • useScrollOffset renamed from useScrollViewOffset -- deprecated alias still works temporarily
  • Shared value .value access is synchronous on UI thread but asynchronous on JS thread -- don't rely on immediate reads after writes on JS thread
  • useWorkletCallback removed -- replace with useCallback + 'worklet' directive
  • React Compiler compatibility: use sv.get() and sv.set() instead of direct .value access when using React Compiler
  • combineTransition removed -- use EntryExitTransition.entering(entering).exiting(exiting)
  • Object shared values: reassign the entire object, never mutate individual properties -- mutations break reactivity tracking
  • Removing an animated style from a view does not unset the animated values -- explicitly set properties to undefined to reset
  • On New Architecture, layout animations use nativeID internally -- don't overwrite it on animated components

</red_flags>


<critical_reminders>

CRITICAL REMINDERS

(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)

Failure to follow these rules will cause animation failures, infinite loops, and crashes on the UI thread.

</critical_reminders>

Files (skills)
  • examples
    • core.md 10.3 KB
      Loading…
    • gestures.md 7.4 KB
      Loading…
    • layout-animations.md 6.3 KB
      Loading…
    • scroll-animations.md 7 KB
      Loading…
  • reference.md 7.6 KB
    Loading…
  • SKILL.md 18.7 KB
    ---
    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.
    
    ```typescript
    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 = () => {
        height.value = withTiming(
          height.value === COLLAPSED_HEIGHT ? EXPANDED_HEIGHT : COLLAPSED_HEIGHT,
          { duration: ANIMATION_DURATION }
        );
      };
    
      return (
        <Pressable onPress={toggle}>
          <Animated.View style={[styles.card, animatedStyle]}>
            <Text>Content</Text>
          </Animated.View>
        </Pressable>
      );
    }
    ```
    
    **Why good:** static styles stay in StyleSheet, only dynamic height in useAnimatedStyle, named constants for dimensions and durations, Animated.View receives the animated style
    
    **Key rules:**
    
    - Only animate dynamic properties in `useAnimatedStyle` -- static styles belong in `StyleSheet.create`
    - Never mutate shared values inside `useAnimatedStyle` -- it is read-only
    - Always apply animated styles to `Animated.*` components, not regular `View`/`Text`
    
    See [examples/core.md](examples/core.md) for complete examples including React Compiler compatibility (`get()`/`set()`).
    
    ---
    
    ### Pattern 2: withSpring and withTiming
    
    `withTiming` is duration-based (predictable timing). `withSpring` is physics-based (natural feel). Choose based on UX intent.
    
    ```typescript
    // Physics-based spring (natural, bouncy)
    sv.value = withSpring(TARGET, { damping: 100, stiffness: 800 });
    
    // Duration-based spring (controlled timing with spring feel)
    sv.value = withSpring(TARGET, { duration: 500, dampingRatio: 0.8 });
    
    // Timing with easing
    sv.value = withTiming(TARGET, {
      duration: ANIMATION_DURATION,
      easing: Easing.bezierFn(0.25, 0.1, 0.25, 1),
    });
    ```
    
    **Reanimated 4 spring change:** `restDisplacementThreshold` and `restSpeedThreshold` are removed. Replaced by `energyThreshold` (relative to animation, default `6e-9`). In most cases, removing the old thresholds is sufficient -- no need to set `energyThreshold` manually.
    
    **Duration gotcha:** In v4, actual spring completion time = perceptual `duration` x 1.5. Divide existing duration values by 1.5 for equivalent behavior when migrating from v3.
    
    See [examples/core.md](examples/core.md) for spring config comparison and withDecay.
    
    ---
    
    ### Pattern 3: Layout Animations (Entering/Exiting)
    
    Predefined animations for component mount/unmount. Apply to `Animated.*` components via `entering` and `exiting` props.
    
    ```typescript
    import Animated, { FadeIn, FadeOutLeft } from "react-native-reanimated";
    
    const ANIMATION_DURATION = 400;
    const ANIMATION_DELAY = 100;
    
    function NotificationBanner({ visible }: { visible: boolean }) {
      if (!visible) return null;
    
      return (
        <Animated.View
          entering={FadeIn.duration(ANIMATION_DURATION).delay(ANIMATION_DELAY)}
          exiting={FadeOutLeft.duration(ANIMATION_DURATION)}
          style={styles.banner}
        >
          <Text>New notification</Text>
        </Animated.View>
      );
    }
    ```
    
    **Available builders:** `FadeIn`, `SlideInRight`, `ZoomIn`, `BounceIn`, `FlipInEasyX`, `LightSpeedInRight`, `RotateIn`, `PinwheelIn`, and all directional variants (Up/Down/Left/Right) plus corresponding `Out` variants.
    
    **Modifiers:** `.duration(ms)`, `.delay(ms)`, `.springify()` (with `.damping()`, `.stiffness()`, `.mass()`), `.withInitialValues()`, `.withCallback()`, `.reduceMotion()`.
    
    **Performance tip:** Define animation builders outside components or in `useMemo` -- creating them inline in render causes unnecessary object allocation.
    
    See [examples/layout-animations.md](examples/layout-animations.md) for custom builders, staggered lists, and `EntryExitTransition`.
    
    ---
    
    ### Pattern 4: Gesture Integration
    
    Reanimated integrates with `react-native-gesture-handler`. Gesture callbacks are **automatically workletized** -- you can access shared values directly without the `'worklet'` directive.
    
    ```typescript
    import { Gesture, GestureDetector } from "react-native-gesture-handler";
    import Animated, {
      useSharedValue,
      useAnimatedStyle,
      withDecay,
    } from "react-native-reanimated";
    
    function DraggableCard() {
      const offsetX = useSharedValue(0);
    
      const pan = Gesture.Pan()
        .onChange((e) => {
          offsetX.value += e.changeX;
        })
        .onFinalize((e) => {
          offsetX.value = withDecay({ velocity: e.velocityX, rubberBandEffect: true });
        });
    
      const animatedStyle = useAnimatedStyle(() => ({
        transform: [{ translateX: offsetX.value }],
      }));
    
      return (
        <GestureDetector gesture={pan}>
          <Animated.View style={[styles.card, animatedStyle]} />
        </GestureDetector>
      );
    }
    ```
    
    **Why good:** `onChange` gives delta values (not absolute), `onFinalize` adds momentum with `withDecay`, gesture callbacks access shared values directly on UI thread
    
    **Key points:**
    
    - Use `onChange` for incremental updates (delta), `onUpdate` for absolute position
    - `GestureHandlerRootView` must wrap your app near the root
    - This skill covers the Reanimated side of gesture animations -- for gesture configuration details (tap, pinch, fling, simultaneous gestures), see the gesture handler skill
    
    See [examples/gestures.md](examples/gestures.md) for swipe-to-dismiss, bottom sheet, and combined gestures.
    
    ---
    
    ### Pattern 5: Scroll-Driven Animations
    
    Use `useScrollOffset` to track scroll position as a shared value. Combine with `interpolate` for parallax, collapsing headers, and fade effects.
    
    ```typescript
    import Animated, {
      useAnimatedRef,
      useScrollOffset,
      useAnimatedStyle,
      interpolate,
      Extrapolation,
    } from "react-native-reanimated";
    
    const HEADER_MAX = 200;
    const HEADER_MIN = 60;
    
    function CollapsibleHeader() {
      const scrollRef = useAnimatedRef<Animated.ScrollView>();
      const scrollOffset = useScrollOffset(scrollRef);
    
      const headerStyle = useAnimatedStyle(() => ({
        height: interpolate(
          scrollOffset.value,
          [0, HEADER_MAX - HEADER_MIN],
          [HEADER_MAX, HEADER_MIN],
          Extrapolation.CLAMP
        ),
      }));
    
      return (
        <>
          <Animated.View style={[styles.header, headerStyle]} />
          <Animated.ScrollView ref={scrollRef}>
            {/* content */}
          </Animated.ScrollView>
        </>
      );
    }
    ```
    
    **Why good:** `useScrollOffset` auto-detects horizontal/vertical, no manual scroll event handler needed, `Extrapolation.CLAMP` prevents values outside the range
    
    **Reanimated 4 rename:** `useScrollViewOffset` -> `useScrollOffset` (deprecated alias remains temporarily).
    
    See [examples/scroll-animations.md](examples/scroll-animations.md) for parallax, sticky elements, and scroll-to-hide tab bar.
    
    ---
    
    ### Pattern 6: Interpolation
    
    Map one value range to another. `interpolate` for numbers, `interpolateColor` for color transitions.
    
    ```typescript
    import {
      interpolate,
      interpolateColor,
      Extrapolation,
    } from "react-native-reanimated";
    
    // Number interpolation: scroll position -> opacity
    const opacity = interpolate(
      scrollY.value,
      [0, 100], // input range
      [1, 0], // output range
      Extrapolation.CLAMP,
    );
    
    // Color interpolation: progress -> background
    const backgroundColor = interpolateColor(
      progress.value,
      [0, 0.5, 1], // input range
      ["#FF0000", "#FFFF00", "#00FF00"], // output colors (red -> yellow -> green)
    );
    ```
    
    **Extrapolation options:** `CLAMP` (cap at edges), `EXTEND` (extrapolate linearly), `IDENTITY` (return input value). Can set left/right independently: `{ extrapolateLeft: Extrapolation.CLAMP, extrapolateRight: Extrapolation.EXTEND }`.
    
    **`interpolateColor` modes:** `'RGB'` (default) or `'HSV'`. HSV produces more perceptually uniform transitions for hue changes.
    
    See [examples/core.md](examples/core.md) for multi-step interpolation and color transition examples.
    
    ---
    
    ### Pattern 7: Worklet Functions
    
    Functions that run on the UI thread. Mark with `'worklet'` directive. Reanimated auto-workletizes callbacks in `useAnimatedStyle`, gesture handlers, and animation callbacks -- you only need explicit `'worklet'` for standalone helper functions.
    
    ```typescript
    import { scheduleOnRN } from "react-native-worklets";
    
    function clampValue(value: number, min: number, max: number) {
      "worklet";
      return Math.min(Math.max(value, min), max);
    }
    
    // Use in useAnimatedStyle -- auto-workletized, no directive needed
    const style = useAnimatedStyle(() => ({
      opacity: clampValue(progress.value, 0, 1),
    }));
    ```
    
    **Reanimated 4 threading changes:**
    
    | Reanimated 3         | Reanimated 4 (react-native-worklets) |
    | -------------------- | ------------------------------------ |
    | `runOnJS(fn)("arg")` | `scheduleOnRN(fn, "arg")`            |
    | `runOnUI(fn)("arg")` | `scheduleOnUI(fn, "arg")`            |
    
    **When you need explicit `'worklet'`:**
    
    - Standalone helper functions called from other worklets
    - Functions passed to `scheduleOnUI`
    
    **When you do NOT need it:**
    
    - `useAnimatedStyle` callbacks (auto-workletized)
    - Gesture handler callbacks (auto-workletized)
    - Animation callbacks (auto-workletized)
    
    ---
    
    ### Pattern 8: CSS Animations and Transitions (Reanimated 4)
    
    Declarative animation API modeled after web CSS. Best for state-driven animations. Worklet API remains for gesture/scroll-driven scenarios.
    
    ```typescript
    import Animated from "react-native-reanimated";
    
    const TRANSITION_DURATION = 300;
    
    function ToggleBox({ expanded }: { expanded: boolean }) {
      return (
        <Animated.View
          style={{
            height: expanded ? 200 : 60,
            opacity: expanded ? 1 : 0.5,
            transitionProperty: "height, opacity",
            transitionDuration: `${TRANSITION_DURATION}ms`,
            transitionTimingFunction: "ease-in-out",
          }}
        />
      );
    }
    ```
    
    **CSS animation keyframes:**
    
    ```typescript
    const PULSE_DURATION = 1000;
    
    <Animated.View
      style={{
        animationName: {
          from: { transform: [{ scale: 1 }] },
          to: { transform: [{ scale: 1.1 }] },
        },
        animationDuration: `${PULSE_DURATION}ms`,
        animationIterationCount: "infinite",
        animationDirection: "alternate",
        animationTimingFunction: "ease-in-out",
      }}
    />
    ```
    
    **When to use CSS vs worklets:**
    
    - CSS -- state-driven toggles, hover effects, simple transitions (less code, better optimizable)
    - Worklets -- gesture-driven, scroll-driven, frame-by-frame control, complex orchestration
    
    </patterns>
    
    ---
    
    <red_flags>
    
    ## RED FLAGS
    
    **High Priority Issues:**
    
    - Passing animated styles to regular `View`/`Text` instead of `Animated.View`/`Animated.Text` -- causes silent failure or crash
    - Mutating shared values inside `useAnimatedStyle` -- causes infinite re-evaluation loops
    - Using `react-native-reanimated/plugin` in Babel config with Reanimated 4 -- must use `react-native-worklets/plugin` (and it must be last in the plugins array)
    - Using Reanimated 4.x with Legacy Architecture (old bridge) -- Reanimated 4 is New Architecture only
    - Animating static properties in `useAnimatedStyle` instead of keeping them in `StyleSheet` -- wastes UI thread resources
    - Using `restDisplacementThreshold`/`restSpeedThreshold` in `withSpring` -- removed in v4, replaced by `energyThreshold`
    
    **Medium Priority Issues:**
    
    - Creating layout animation builders inline in render -- allocates objects every render; define outside component or in `useMemo`
    - Using `runOnJS`/`runOnUI` instead of `scheduleOnRN`/`scheduleOnUI` -- old API moved to `react-native-worklets`
    - Missing `GestureHandlerRootView` at app root -- gestures silently fail without it
    - Using `useAnimatedGestureHandler` -- removed in v4, migrate to Gesture Handler 2's `Gesture` API
    
    **Gotchas and Edge Cases:**
    
    - `withSpring` duration: actual completion time = perceptual `duration` x 1.5 -- divide v3 duration values by 1.5 when migrating
    - `useScrollOffset` renamed from `useScrollViewOffset` -- deprecated alias still works temporarily
    - Shared value `.value` access is synchronous on UI thread but asynchronous on JS thread -- don't rely on immediate reads after writes on JS thread
    - `useWorkletCallback` removed -- replace with `useCallback` + `'worklet'` directive
    - React Compiler compatibility: use `sv.get()` and `sv.set()` instead of direct `.value` access when using React Compiler
    - `combineTransition` removed -- use `EntryExitTransition.entering(entering).exiting(exiting)`
    - Object shared values: reassign the entire object, never mutate individual properties -- mutations break reactivity tracking
    - Removing an animated style from a view does not unset the animated values -- explicitly set properties to `undefined` to reset
    - On New Architecture, layout animations use `nativeID` internally -- don't overwrite it on animated components
    
    </red_flags>
    
    ---
    
    <critical_reminders>
    
    ## CRITICAL REMINDERS
    
    **(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`)**
    
    **Failure to follow these rules will cause animation failures, infinite loops, and crashes on the UI thread.**
    
    </critical_reminders>
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.