2nd/10_Wiki/Topics/Coding/RN_Reanimated_3_Patterns.md

id, title, category, status, source_trust_level, verification_status, created_at, updated_at, tags, tech_stack, applied_in, aliases

id	title	category	status	source_trust_level	verification_status	created_at	updated_at	tags	tech_stack	applied_in	aliases
rn-reanimated-3-patterns	Reanimated 3 — Worklet / shared value / 60fps	Coding	draft	B	conceptual	2026-05-09	2026-05-09	react-native reanimated animation vibe-coding	language applicable_to TS / React Native React Native		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

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

Basic

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)

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

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

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)

const pan = Gesture.Pan().onEnd(() => {
  if (x.value > 200) {
    runOnJS(navigation.goBack)();
  }
});

Layout animations

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)

<Animated.View sharedTransitionTag="hero">...</Animated.View>

withSpring / withTiming / withDecay

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

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

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