---
id: rn-reanimated-3-patterns
title: Reanimated 3 — Worklet / shared value / 60fps
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [react-native, reanimated, animation, vibe-coding]
tech_stack: { language: "TS / React Native", applicable_to: ["React Native"] }
applied_in: []
aliases: [Reanimated 3, useSharedValue, useAnimatedStyle, worklet, runOnJS]
---

# Reanimated 3

> RN 의 60fps animation 표준. **JS thread 안 거치는 worklet**. shared value + animated style. Gesture Handler 와 페어. v3 = 자동 worklet (babel plugin).

## 📖 핵심 개념
- Worklet: UI thread 에서 실행되는 JS 함수 (반응형).
- Shared value: worklet ↔ JS 양쪽에서 read/write.
- Derived value: shared value → 계산.
- runOnJS / runOnUI: thread 간 호출.

## 💻 코드 패턴

### Setup
```bash
yarn add react-native-reanimated
# babel.config.js: 'react-native-reanimated/plugin' 추가 (마지막)
```

### Basic
```tsx
import Animated, { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';

function Box() {
  const offset = useSharedValue(0);

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

  return (
    <>
      <Animated.View style={[styles.box, style]} />
      <Button onPress={() => { offset.value = withSpring(offset.value + 100); }} />
    </>
  );
}
```

### Gesture (with Gesture Handler 2)
```tsx
import { GestureDetector, Gesture } from 'react-native-gesture-handler';
import Animated, { useSharedValue, useAnimatedStyle, withSpring } from 'react-native-reanimated';

function Draggable() {
  const x = useSharedValue(0);
  const y = useSharedValue(0);

  const pan = Gesture.Pan()
    .onChange((e) => {
      x.value += e.changeX;
      y.value += e.changeY;
    })
    .onEnd(() => {
      x.value = withSpring(0);
      y.value = withSpring(0);
    });

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

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

### Derived value
```tsx
const progress = useSharedValue(0);
const opacity = useDerivedValue(() => Math.min(progress.value / 100, 1));
const scale = useDerivedValue(() => 1 + progress.value * 0.005);

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

### Scroll-driven
```tsx
import Animated, { useAnimatedScrollHandler, useSharedValue, useAnimatedStyle, interpolate } from 'react-native-reanimated';

const scrollY = useSharedValue(0);
const onScroll = useAnimatedScrollHandler({ onScroll: (e) => { scrollY.value = e.contentOffset.y; } });

const headerStyle = useAnimatedStyle(() => ({
  height: interpolate(scrollY.value, [0, 200], [120, 60], 'clamp'),
}));

return (
  <>
    <Animated.View style={[styles.header, headerStyle]} />
    <Animated.ScrollView onScroll={onScroll} scrollEventThrottle={16}>...</Animated.ScrollView>
  </>
);
```

### runOnJS (UI → JS thread)
```tsx
const pan = Gesture.Pan().onEnd(() => {
  if (x.value > 200) {
    runOnJS(navigation.goBack)();
  }
});
```

### Layout animations
```tsx
import Animated, { FadeIn, FadeOut, SlideInRight } from 'react-native-reanimated';

<Animated.View entering={FadeIn} exiting={FadeOut}>...</Animated.View>
<Animated.View entering={SlideInRight.duration(300)}>...</Animated.View>
```

### Shared element (v3 experimental)
```tsx
<Animated.View sharedTransitionTag="hero">...</Animated.View>
```

### withSpring / withTiming / withDecay
```ts
offset.value = withSpring(100, { damping: 12, stiffness: 100 });
offset.value = withTiming(100, { duration: 300, easing: Easing.out(Easing.cubic) });
offset.value = withDecay({ velocity: 500, deceleration: 0.998 });
```

### Sequence / parallel
```ts
import { withSequence, withDelay, withRepeat } from 'react-native-reanimated';

x.value = withSequence(
  withTiming(100, { duration: 200 }),
  withTiming(0, { duration: 200 }),
);

scale.value = withRepeat(withTiming(1.1, { duration: 500 }), -1, true); // 무한 yoyo
```

### Callback (animation 끝)
```ts
offset.value = withSpring(100, {}, (finished) => {
  if (finished) runOnJS(onSettled)();
});
```

## 🤔 의사결정 기준
| 상황 | 추천 |
|---|---|
| 60fps 인터랙션 | Reanimated worklet |
| 단순 enter/exit | Animated.timing 또는 LayoutAnimation |
| 제스처 | Gesture Handler 2 + Reanimated |
| 차트 / SVG | react-native-svg + Reanimated |
| 3D / 게임 | Skia + Reanimated |
| 단순 transition | css-style (Animated API 옛것) |

## ❌ 안티패턴
- **JS state 로 60fps animation**: jank.
- **Worklet 안 외부 변수 (closure)**: dependency 명시 필요.
- **runOnJS 매 frame**: 의미 없음. shared value.
- **Worklet 안 async**: 안 됨. JS 로 보내기.
- **Babel plugin 누락**: build 깨짐.
- **scrollEventThrottle 누락 / 큼**: scroll animation 끊김.
- **shared value 의 .value 를 worklet 외부에서 매 렌더 read**: re-render. useDerivedValue 또는 useAnimatedStyle.

## 🤖 LLM 활용 힌트
- v3 자동 worklet (babel) — 함수 안 쓰면 ` 'worklet';` 명시.
- Gesture Handler 2 + Reanimated 가 표준.
- runOnJS 는 마지막에만.

## 🔗 관련 문서
- [[React_Animation_Performance]]
- [[RN_Hermes_Optimization]]
- [[React_Native_Bridge_Performance]]