reanimated-core

Files (2)

• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Core Hooks & the Worklet Model

The foundation of every Reanimated animation: shared values, worklets, and the two-thread model. Get this right and everything else composes cleanly.

## The two-thread model

React Native runs your JS logic on the **JS thread**. Reanimated runs animations on the **UI thread** via *worklets* — small functions that are copied to a separate JS runtime on the UI thread and executed there, in sync with the display's refresh rate.

| | JS thread | UI thread (worklets) |
| --- | --- | --- |
| **Runs** | React render, effects, event handlers, business logic | `useAnimatedStyle`, `useDerivedValue`, gesture callbacks, functions marked `'worklet'` |
| **Blocked by** | Heavy JS work, list rendering, network parsing | Nothing you write should block it — keep worklets tiny |
| **Frame budget** | Not frame-critical | 16.6ms @ 60fps, 8.3ms @ 120fps ProMotion |
| **Can call** | `runOnUI` to schedule worklets | `runOnJS` to call back into JS-only code |

Shared values are the bridge: they can be read/written from both threads, and mutating one on the UI thread never round-trips through React.

Keep all motion on the UI thread: everything that animates must run in a worklet (`useAnimatedStyle`, `useDerivedValue`, gesture callbacks). Never `setState` on every frame to drive motion — that hops to the JS thread and drops frames.

## The golden rule: never touch `.value` during render

Read and write `shared.value` **only** inside:

- worklets (functions with the `'worklet'` directive),
- `useAnimatedStyle` / `useAnimatedProps` / `useDerivedValue` callbacks,
- `useAnimatedReaction`,
- gesture callbacks (`onBegin`/`onUpdate`/`onEnd`),
- `useEffect` / event handlers (JS thread — fine to write, e.g. `sv.value = withTiming(1)`).

Never read or write it in the component render body.

```tsx
// Bad — reading .value during render
const Box = () => {
  const width = useSharedValue(100);
  return <View style={{ width: width.value }} />; // ❌ no subscription, warns/crashes
}
```

```tsx
// Good — read .value inside an animated style worklet
const Box = () => {
  const width = useSharedValue(100);
  const style = useAnimatedStyle(() => ({ width: width.value }));
  return <Animated.View style={style} />;
}
```

## `useSharedValue`

A mutable value that lives on the UI thread and drives animations. Mutating `.value` does **not** trigger a React re-render.

```tsx
import { useSharedValue, withSpring } from 'react-native-reanimated';
import { SPRING } from './constants';

const scale = useSharedValue(1);

// Writing from the JS thread (event handler) is fine:
const onPressIn = () => { scale.value = withSpring(0.96, SPRING); };
const onPressOut = () => { scale.value = withSpring(1, SPRING); };
```

## `useAnimatedStyle`

Returns a style object computed on the UI thread. Reanimated auto-tracks any shared value you read inside — there is no manual dependency array.

```tsx
// Good — animate transform + opacity (composited, no layout pass)
const style = useAnimatedStyle(() => ({
  transform: [{ scale: scale.value }],
  opacity: opacity.value,
}));

return <Animated.View style={[styles.card, style]} />;
```

```tsx
// Bad — animating layout props triggers a layout pass every frame → jank
const style = useAnimatedStyle(() => ({
  width: width.value,
  marginTop: offset.value,
}));
```

The callback is an implicit worklet — you do **not** write `'worklet'` inside hook callbacks; Reanimated's Babel plugin adds it.

## `useDerivedValue`

Compute a new shared value from others on the UI thread. Use it to keep derivation off the JS thread and avoid duplicated math across styles.

```tsx
// Good — derive once, consume in multiple styles
const progress = useSharedValue(0);
const opacity = useDerivedValue(() => progress.value);         // 0 → 1
const translateY = useDerivedValue(() => (1 - progress.value) * 20);

const style = useAnimatedStyle(() => ({
  opacity: opacity.value,
  transform: [{ translateY: translateY.value }],
}));
```

## `useAnimatedReaction`

Run a side effect on the UI thread when a computed value changes — the UI-thread equivalent of "watch this, then do that". Great for triggering a second animation, or hopping to JS with `runOnJS` at a threshold.

```tsx
// Good — fire haptics on the JS thread when a drag crosses a threshold
useAnimatedReaction(
  () => translateX.value > SWIPE_THRESHOLD,   // prepare (worklet)
  (isPastThreshold, wasPastThreshold) => {     // react (worklet)
    if (isPastThreshold && !wasPastThreshold) {
      runOnJS(triggerHaptic)();
    }
  },
);
```

From hzblj/skills, MIT.

More from hzblj/skills