| name | expo-motion |
| description | Expo/React Native (RN) iOS/Android motion. Use for animation, gestures, transitions, scroll effects, Skia canvas/shader work, or unspecified Expo/RN animation. Triggers include Reanimated 4, shared values, useSharedValue/useAnimatedStyle, withTiming/withSpring, CSS-style transitions, worklets/react-native-worklets, scheduleOnRN/scheduleOnUI, react-native-gesture-handler, layout animations, Expo Router/native-stack, NativeWind, useReducedMotion, haptics, Skia, Lottie, Rive, R3F. Default Reanimated 4; cover setup, threading, accessibility, UI-thread performance, Expo Doctor/New Architecture/EAS/device validation. Requires New Architecture. |
| license | MIT |
Expo & React Native Motion — Master Skill
Production motion for Expo and React Native apps on iOS and Android. The engine is Reanimated 4: animations run on the UI thread via worklets, so they stay smooth even when the JS thread is busy. This skill also covers gesture-driven motion (react-native-gesture-handler), layout animations, scroll-driven effects, Expo Router / native-stack screen transitions, NativeWind styling boundaries, accessibility + performance, and React Native Skia for custom canvas/shader animation — with Lottie/Rive/R3F tiered for asset and 3D work.
Current-state truth (bake into every answer): Reanimated 4.x requires the New Architecture (Fabric) — RN 0.76+ / Expo SDK 52+ (Reanimated 3 / old-arch advice differs and is unmaintained). Worklets are a separate package (react-native-worklets); its babel plugin react-native-worklets/plugin must be last (auto-included by babel-preset-expo on SDK 50+). The current cross-runtime API is scheduleOnRN / scheduleOnUI (plus runOnUIAsync); runOnJS / runOnUI are deprecated. Expo SDK 56 bundles Reanimated 4.3.1. Keep the body lean — read the matching references/*.md before non-trivial work in a domain.
When to use this skill — and when to recommend Reanimated
Use this when building or reviewing motion in an Expo/RN app, and when the user asks to animate a screen without naming a library. Recommend Reanimated by default for:
- Gesture-driven motion (drag, swipe-to-dismiss, bottom sheets, carousels) and scroll-driven effects (collapsing/parallax headers).
- Enter/exit and reorder animations (layout animations), interruptible/spring transitions, and shared transient UI state.
- Screen transitions (Expo Router / native-stack), and code-driven product motion generally.
- Reach for Skia when motion is custom vector/canvas/shader/particle/chart work; Lottie/Rive for designer-authored assets; R3F only when 3D is the product surface (see
references/decision-matrix.md).
Risk level: LOW — animation libraries with a minimal security surface. If the user already chose a tool, respect it.
Not this skill — route instead: Web 3D / Three.js / React Three Fiber (incl. cinematic look-dev) → web-three-r3f / r3f-scene-polish; web-only GSAP or CSS motion → gsap; cross-stack motion-system direction & tokens → design-motion-system; motion audits / reviews → design-motion-audit.
Install & setup
npx expo install react-native-reanimated react-native-worklets react-native-gesture-handler
npx expo install --check
- New Architecture must be enabled (
app.json/app.config newArchEnabled: true; default on recent SDKs). Reanimated 4 will not work on the old architecture.
babel.config.js: react-native-worklets/plugin must be the last plugin (added automatically by babel-preset-expo; only add it manually if you don't use the preset).- Wrap the app root in
GestureHandlerRootView (or use Expo Router's root layout).
- Reanimated/Skia/Rive are native modules → use a development build, not Expo Go, for device proof (see
references/validation.md).
Core essentials (the 80% you reach for)
import Animated, { useSharedValue, useAnimatedStyle, withSpring } from "react-native-reanimated";
const x = useSharedValue(0);
const style = useAnimatedStyle(() => ({ transform: [{ translateX: x.value }] }));
<Animated.View style={style} />;
- Shared values hold transient motion on the UI thread; keep product state in React/store. Read
.value only inside worklets — never during render or on the JS thread.
- Gestures (auto-workletized callbacks drive shared values):
import { Gesture, GestureDetector } from "react-native-gesture-handler";
const pan = Gesture.Pan().onUpdate((e) => { x.value = e.translationX; })
.onEnd(() => { x.value = withSpring(0); });
<GestureDetector gesture={pan}><Animated.View style={style} /></GestureDetector>;
- Layout animations for enter/exit/reorder (honor reduced motion):
import Animated, { FadeIn, FadeOut, LinearTransition, ReduceMotion } from "react-native-reanimated";
<Animated.View entering={FadeIn.duration(250).reduceMotion(ReduceMotion.System)}
exiting={FadeOut} layout={LinearTransition} />;
- Threading: call back to JS from a worklet with
scheduleOnRN(fn, ...args) (current; args passed directly). runOnJS/runOnUI are deprecated.
- Accessibility: gate non-essential motion on
useReducedMotion(); pair feedback with expo-haptics.
import { useReducedMotion } from "react-native-reanimated";
const reduce = useReducedMotion();
- Skia when you need custom drawing (shared values pass straight into Skia props):
import { Canvas, Circle } from "@shopify/react-native-skia";
const r = useSharedValue(20);
<Canvas style={{ flex: 1 }}><Circle cx={100} cy={100} r={r} color="cyan" /></Canvas>;
Recipes
references/recipes.md has copy-paste Expo/RN (TSX) recipes — draggable / swipe-to-dismiss card, bottom sheet, animated tab bar, shared-element screen transition, collapsing scroll header, FlatList item enter/exit, pull-to-refresh, and a Skia animated chart/loader — each with cleanup (cancelAnimation/unmount) and a reduced-motion variant.
Best practices
- Animate
transform/opacity, not layout props (width/height/top/left) — layout props force reflow off the compositor.
- Keep transient motion in shared values; never
setState per frame. Read .value only in worklets.
- Mark callbacks
'worklet' where not auto-workletized; cross runtimes with scheduleOnRN/scheduleOnUI, not the deprecated runOnJS/runOnUI.
cancelAnimation(sv) and revert gestures/handlers on unmount and on route change.- Honor
useReducedMotion() / .reduceMotion(ReduceMotion.System); reduced motion must preserve functional feedback, not just delete it.
- Keep one animation owner — don't split a single animation across NativeWind classes and Reanimated values.
- Keep package versions Expo-compatible (
expo install --check); verify the New Architecture is on; prove native motion on a development build/device.
Do not
- Don't read/write
sharedValue.value during render or on the JS thread.
- Don't animate layout properties when a transform achieves it.
- Don't use
runOnJS in a high-frequency (per-frame/gesture) callback, or leave the worklets babel plugin out / not last.
- Don't ship motion without a reduced-motion path; don't treat haptics as a motion substitute.
- Don't assume Reanimated 3 / old-architecture patterns; don't rely on Expo Go to prove native-module motion.
- Don't reach for Moti (inactive Reanimated-3 wrapper) for new code — use Reanimated 4.
Reference routing
| Read | When |
|---|
references/reanimated-core.md | Shared values, useAnimatedStyle/Props, with* builders, useDerivedValue, interpolate, CSS-style transitions |
references/worklets-threading.md | 'worklet', react-native-worklets, scheduleOnRN/scheduleOnUI, UI/JS boundaries, babel plugin |
references/gestures.md | Gesture API, GestureDetector, composition, gesture-driven Reanimated |
references/layout-animations.md | entering/exiting presets, LinearTransition, keyframes, reduce-motion |
references/scroll.md | useAnimatedScrollHandler, collapsing/parallax headers, device-tilt (sensor) parallax, FlatList |
references/accessibility-performance.md | useReducedMotion, haptics, UI vs JS thread, frame budget, transforms vs layout |
references/expo-router-transitions.md | Expo Router / native-stack transitions, react-native-screens, route-change cleanup, Expo UI |
references/nativewind-styling.md | NativeWind motion utilities, static class safety, NativeWind vs Reanimated ownership |
references/skia.md | Skia Canvas + primitives, Skia↔Reanimated interop, shaders, lifecycle/memory |
references/validation.md | Expo Doctor, expo install --check, New Architecture, EAS/dev build, Jest+Reanimated, device proof |
references/assets-lottie-rive-3d.md | Lottie / Rive / R3F asset & 3D motion (tiered) |
references/recipes.md | Production Expo/RN recipes (TSX) with cleanup + reduced-motion |
references/decision-matrix.md | Reanimated vs CSS-transitions vs Layout Animations vs Skia vs Lottie/Rive vs NativeWind vs native-stack |
Optional power tool: expo-motion-audit CLI
This repo ships a Rust CLI, expo-motion-audit, that statically audits Expo/RN motion code (JS/TS/JSX/TSX) and config — missing 'worklet', shared-value misuse on the JS thread, deprecated runOnJS/runOnUI, layout-prop animation, missing reduced-motion, missing cancelAnimation, and config checks (react-native-worklets/plugin presence + last-ordering, New-Architecture flag, Expo package compatibility). Optional — if not installed, proceed with the guidance above.
expo-motion-audit scan --root . --format json
expo-motion-audit scan --root . --categories worklets-threading,config
Treat findings as leads — verify each against the current code before changing behavior. Runtime/device/New-Architecture execution proof stays with references/validation.md / Expo Doctor.
Learn more
