Animate Expo

Building Animations in Expo

<!-- CORE-OVERLAY-START -->

This repository (Asymmetric-al/core)

This skill is for React Native / Expo motion only. Core's Next.js apps should use animate, emil-design-engineering, and anim instead. Reconcile this overlay after upstream refreshes before running bun run skills:sync.

Triggers

• Explicit Expo or React Native animation, gesture, sheet, or haptics work.
• Do not load it for Core web apps (apps/admin, apps/donor, apps/missionary) or shared packages/ui web motion.

Workflow

1. Confirm the request is native/Expo before applying Reanimated recipes.
2. For Core Next.js surfaces, stop and load animate plus anim.

Checklist

• The target runtime is Expo/React Native, not Core's App Router apps.
• Web motion still follows Core tokens and Base UI.

<!-- CORE-OVERLAY-END -->

A construction skill for React Native. It turns a request for motion into an implementation that survives a strict review on a real device — not in the simulator, not on a flagship phone in dev mode.

Mobile changes three things about animation, and everything in this skill follows from them:

1. There is no hover. Every affordance the web puts in hover has to live in press, position, or nothing.
2. There are two runtimes. Worklets (Reanimated 4) makes this explicit: the React Native runtime, where React renders and your app logic runs, and the UI runtime, where worklets run every frame (plus optional worker runtimes for background work). An animation that touches the RN runtime stutters the moment the app does anything else. The whole craft is keeping motion on the UI runtime.
3. The user's finger is on the element. Gestures are the primary input, so interruptibility and velocity handoff aren't polish — they're the baseline.

Operating Posture

You are a senior mobile engineer building the animation yourself. Make the call, state the reasoning in one line, write the code. Never present motion options as a menu.

Two failure modes, and the first is worse:

1. Animating something that shouldn't animate. The gate below exists to produce zero lines of code sometimes.
2. Animating the right thing on the wrong thread — a setState per frame, a PanResponder, an animated height. It looks fine in dev on your phone and drops to 20fps on a three-year-old Android.

Hard Rules

1. Run the sequence in order. Steps 1 and 2 gate everything.
2. Reanimated, not core Animated. Core Animated can't be driven by a gesture without crossing the bridge, and useNativeDriver refuses anything but transform and opacity anyway. Reanimated worklets run on the UI thread and keep running while JS is busy.
3. No approximated values. Curves and spring configs come from the tables below.
4. Reduced motion ships with the animation, not as a follow-up.
5. Feel is judged on a release build on the slowest device you support. Nothing else counts as verified.

The Build Sequence

1. Should this animate at all?

Tab switches never slide. Tabs are peers, not a hierarchy — sliding implies depth that isn't there, and the user pays for it dozens of times a session. animation: 'none'.

If the request fails this gate, say so and don't write it.

2. What is the purpose?

Name it in one word before continuing: feedback, spatial consistency, state indication, preventing a jarring change, explanation, or delight (rare tier only).

Can't name it? Don't build it.

3. Pick the tool — cheapest that works

Walk down; stop at the first that fits.

Reach for a shared value only when the value is continuous or interruptible. A press scale is a CSS transition; a drag is a shared value. Using a worklet for a two-state toggle is the mobile equivalent of installing a motion library for a fade.

Dependencies. Install with npx expo install <package> — it resolves the version that matches the project's SDK, which plain npm install won't:

4. Pick the properties

• transform and opacity are free. Everything else is a layout pass. width, height, margin, padding, flex, top, left, gap re-run Yoga on every frame for that node and its siblings.
• The one exception: an absolutely positioned element with no children — a tab pill, a progress bar fill. It's out of flow, so nothing else re-lays-out, and animating width keeps the corner radius that scaleX would smear.
• Never scale(0). Start from scale(0.9–0.97) + opacity: 0. Nothing in the real world appears from nothing.
• transform is an array and order matters — [{ translateY }, { scale }] scales after moving; reversed, the translate gets scaled too. Keep translate first unless you want the multiplication.
• Android shadows are elevation, and animating elevation re-renders the shadow every frame. Animate opacity of a pre-shadowed layer instead.
• Never animate BlurView intensity. On Android it re-renders the blur each frame. Crossfade the opacity of a static BlurView instead.
• Percentages work in translate and are relative to the element's own size — translateY('100%') moves a sheet by its own height whatever its content.

5. Timing or spring

If a finger was involved, use a spring. Springs carry velocity through an interruption; timing curves restart. Everything else uses timing.

Reanimated's spring takes Apple's two designer parameters directly — use this form, not mass/stiffness/damping:

Bounce only when the gesture carried momentum. Overshoot on a menu that faded in feels wrong; overshoot on a card you flicked feels right.

Easing, for everything without a finger on it:

Never ease-in on UI. It starts slow, delaying the exact moment the user is watching. Reanimated's built-ins are as weak as CSS's — use these:

import { Easing } from "react-native-reanimated";

const EASE_OUT = Easing.bezier(0.23, 1, 0.32, 1); // strong ease-out for UI
const EASE_IN_OUT = Easing.bezier(0.77, 0, 0.175, 1); // on-screen movement
const EASE_SHEET = Easing.bezier(0.32, 0.72, 0, 1); // iOS sheet curve

Duration:

Mobile UI animations stay under 300ms, same as web. The platform's own transitions are longer (iOS push is 350ms); match the platform for navigation, beat it everywhere else.

6. Keep it off the JS thread

This is the mobile-specific craft, and it's where most React Native motion dies.

• Never setState from a gesture or scroll handler. One React render per frame is the single biggest cause of jank in RN apps. Shared value → useAnimatedStyle, and React never re-renders at all.
• Never schedule back to the RN runtime inside onUpdate or a scroll handler. scheduleOnRN(fn, ...args) from react-native-worklets — the Reanimated 4 replacement for the deprecated runOnJS(fn)(...args) — queues an RN-runtime call, and in onUpdate that's 60–120× per second. It belongs in onEnd, or in a useAnimatedReaction that fires when a value crosses a threshold.
• Never read a shared value during render (translateY.get() in JSX). It's a snapshot that never updates and it silently desyncs. Never write one during render either — it fires mid-reconciliation, and a re-render you didn't cause replays the write. Touch shared values only in worklets, handlers, and effects.
• Use .get() / .set(), not .value. Same API, but direct .value access is the form the React Compiler can't see through — the Reanimated docs call get/set the compiler-safe way. set also takes a functional update: sv.set((v) => v + 1).
• Functions called from a worklet need 'worklet' as their first line, or they throw at runtime on device while working fine in the debugger.