React Native Reanimated은(는) 무엇을 하나요?
개요
Reanimated는 애니메이션을 네이티브 UI 스레드에서 실행하여, JavaScript 스레드가 바쁠 때에도 60fps(또는 디스플레이 주사율)를 유지합니다. 이는 JSI를 통해 UI 스레드에서 실행되는 작은 JavaScript 함수인 '워크렛(worklet)'을 사용합니다. 제스처 기반 상호작용, 레이아웃 전환, 스크롤 기반 효과, 공유 요소 전환 등 React Native에서 프로덕션 품질의 애니메이션을 위한 표준입니다.
이 스킬은 Reanimated 4(4.7.0, 2026년 9월)를 대상으로 합니다. 버전 4는 새로운 아키텍처(New Architecture)에서만 작동하며, 워크렛을 별도의 react-native-worklets 패키지로 이동시키고 CSS 스타일의 전환 및 애니메이션을 추가했습니다. 여전히 기존 아키텍처를 사용하는 앱은 더 이상 적극적으로 유지보수되지 않는 3.x 버전을 사용해야 합니다.
사용 시기
- 단순한 opacity/transform 이상의 React Native 애니메이션
- 제스처 기반 상호작용 (스와이프하여 삭제, 드래그하여 재정렬, 핀치하여 확대/축소)
- 스크롤 기반 애니메이션 (패럴랙스 헤더, 고정 요소)
- 레이아웃 애니메이션 (리스트에 항목이 들어오거나 나갈 때)
- 화면 간 공유 요소 전환 (4.x에서 실험적)
지침
설정
# Expo: SDK에서 고정된 버전을 설치합니다 (SDK 57: Reanimated 4.5, Worklets 0.10, Gesture Handler 2.32)
npx expo install react-native-reanimated react-native-worklets react-native-gesture-handler
npx expo prebuild # 개발 빌드 전용: ios/ 및 android/ 디렉토리 재생성
# React Native Community CLI
npm install react-native-reanimated react-native-worklets react-native-gesture-handler
cd ios && pod install && cd ..
npm start -- --reset-cache
- Expo:
babel-preset-expo가 Worklets Babel 플러그인을 자동으로 추가하므로babel.config.js에 별도로 명시하지 마십시오. - Community CLI:
babel.config.js의plugins배열 마지막에'react-native-worklets/plugin'을 추가하십시오. Reanimated 3 시절의 이름인react-native-reanimated/plugin도 4.x에서 여전히 동작하지만 레거시 표기입니다. - 각 Reanimated 마이너 버전은 특정
react-native-worklets및 React Native 버전을 요구합니다 (4.7은 Worklets 0.13과 RN 0.86–0.88 필요). 수동 업그레이드 전에 호환성 표를 확인하십시오. - 제스처를 사용하려면 앱 루트를
react-native-gesture-handler의GestureHandlerRootView로 감싸고style={{ flex: 1 }}을 설정하십시오.
공유 값과 애니메이션 스타일
// components/FadeIn.tsx — 공유 값을 사용한 기본 애니메이션
import Animated, { useSharedValue, useAnimatedStyle, withTiming, withSpring } from "react-native-reanimated";
import { type ReactNode, useEffect } from "react";
export function FadeInCard({ children }: { children: ReactNode }) {
const opacity = useSharedValue(0);
const translateY = useSharedValue(20);
useEffect(() => {
opacity.value = withTiming(1, { duration: 600 });
translateY.value = withSpring(0);
}, []);
const animatedStyle = useAnimatedStyle(() => ({
opacity: opacity.value,
transform: [{ translateY: translateY.value }],
}));
return <Animated.View style={[{ backgroundColor: "white", padding: 16 }, animatedStyle]}>{children}</Animated.View>;
}
.value의 읽기와 쓰기는 effect, 이벤트 핸들러, 워크렛 내에서만 수행하고, 렌더링 중에는 절대 하지 마십시오. React Compiler를 사용하는 경우 .value 대신 opacity.get()과 opacity.set(1)을 사용하십시오.
제스처 애니메이션
// components/SwipeToDelete.tsx — 애니메이션이 포함된 스와이프 제스처
import Animated, { useSharedValue, useAnimatedStyle, withSpring } from "react-native-reanimated";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import { scheduleOnRN } from "react-native-worklets";
import type { ReactNode } from "react";
export function SwipeToDelete({ onDelete, children }: { onDelete: () => void; children: ReactNode }) {
const translateX = useSharedValue(0);
const pan = Gesture.Pan()
.onUpdate((event) => {
translateX.value = Math.min(0, event.translationX); // 왼쪽 스와이프만 허용
})
.onEnd((event) => {
if (event.translationX < -150) {
translateX.value = withSpring(-400);
scheduleOnRN(onDelete); // UI 스레드에서 JS 스레드 함수 호출
} else {
translateX.value = withSpring(0); // 원래 위치로 복귀
}
});
const animatedStyle = useAnimatedStyle(() => ({ transform: [{ translateX: translateX.value }] }));
return (
<GestureDetector gesture={pan}>
<Animated.View style={animatedStyle}>{children}</Animated.View>
</GestureDetector>
);
}
scheduleOnRN(fn, ...args)는 4.x에서 더 이상 사용되지 않는 runOnJS(fn)(...args)를 대체합니다. Gesture.Pan()은 Gesture Handler 2의 빌더 API로, Expo SDK 57이 설치하는 방식입니다. Gesture Handler 3은 이를 유지하면서 훅(usePanGesture({ onUpdate, onDeactivate }))을 추가하며, onStart/onEnd는 onActivate/onDeactivate로 이름이 변경되었습니다.
레이아웃 애니메이션
// components/AnimatedList.tsx — 항목이 자동으로 애니메이션되며 들어오고 나갑니다
import Animated, { FadeInDown, FadeOutLeft, LinearTransition } from "react-native-reanimated";
import { Pressable, Text } from "react-native";
type Item = { id: string; title: string };
export function AnimatedList({ items, onRemove }: { items: Item[]; onRemove: (id: string) => void }) {
return (
<Animated.FlatList
data={items}
keyExtractor={(item) => item.id}
itemLayoutAnimation={LinearTransition} // 나머지 행이 제자리로 슬라이드 이동 (단일 열만 가능)
renderItem={({ item, index }) => (
<Animated.View
entering={FadeInDown.delay(index * 100).springify()}
exiting={FadeOutLeft.duration(300)}
style={{ backgroundColor: "white", padding: 16, marginVertical: 4, borderRadius: 8 }}
>
<Text>{item.title}</Text>
<Pressable onPress={() => onRemove(item.id)}><Text style={{ color: "#dc2626" }}>제거</Text></Pressable>
</Animated.View>
)}
/>
);
}
스크롤 기반 애니메이션
// components/ParallaxHeader.tsx — 스크롤 시 패럴랙스 효과
import Animated, {
useAnimatedScrollHandler, useSharedValue, useAnimatedStyle, interpolate, Extrapolation,
} from "react-native-reanimated";
import { Text } from "react-native";
export function ParallaxHeader() {
const scrollY = useSharedValue(0);
const scrollHandler = useAnimatedScrollHandler({
onScroll: (event) => { scrollY.value = event.contentOffset.y; },
});
const headerStyle = useAnimatedStyle(() => ({
height: interpolate(scrollY.value, [-100, 0, 200], [400, 300, 100], Extrapolation.CLAMP),
opacity: interpolate(scrollY.value, [0, 200], [1, 0.3], Extrapolation.CLAMP),
}));
return (
<>
<Animated.View style={[{ backgroundColor: "#2563eb" }, headerStyle]}>
<Text style={{ color: "white", fontSize: 28, fontWeight: "bold" }}>트레일 로그</Text>
</Animated.View>
<Animated.ScrollView onScroll={scrollHandler}>{/* 콘텐츠 */}</Animated.ScrollView>
</>
);
}
오프셋만 필요한 경우 useScrollOffset(animatedRef) (3.x에서는 useScrollViewOffset)를 사용하면 핸들러 없이 공유 값으로 오프셋을 반환합니다.
CSS 전환 및 공유 요소 (Reanimated 4)
// 상태 변경이 자체적으로 애니메이션됩니다: 공유 값, 훅 불필요
<Animated.View
style={{
height: 80,
width: expanded ? 240 : 120,
backgroundColor: expanded ? "#16a34a" : "#2563eb",
transitionProperty: ["width", "backgroundColor"],
transitionDuration: 300,
}}
/>
// 네이티브 스택의 두 화면에서 동일한 태그를 사용하면 요소가 화면 간에 애니메이션됩니다
<Animated.Image sharedTransitionTag="trail-42-photo" source={{ uri: photoUrl }} style={{ width: 120, height: 120 }} />
공유 요소 전환은 4.x에서 실험적이며 기본적으로 비활성화되어 있습니다. 앱의 package.json에 "reanimated": { "staticFeatureFlags": { "ENABLE_SHARED_ELEMENT_TRANSITIONS": true } }를 추가하여 활성화한 후(4.2+), 네이티브 앱을 다시 빌드하십시오. 정적 플래그는 Expo Go에서 변경할 수 없습니다.
예제
예제 1: 카드 스와이프 인터페이스 구축
사용자 프롬프트: "부드러운 애니메이션이 포함된 Tinder 스타일의 카드 스와이프 인터페이스를 구축해 주세요."
// components/SwipeCard.tsx
import Animated, { interpolate, useAnimatedStyle, useSharedValue, withSpring, withTiming } from "react-native-reanimated";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import { scheduleOnRN } from "react-native-worklets";
import { useWindowDimensions } from "react-native";
import type { ReactNode } from "react";
type Props = { children: ReactNode; onSwipe: (direction: "left" | "right") => void };
export function SwipeCard({ children, onSwipe }: Props) {
const { width } = useWindowDimensions();
const x = useSharedValue(0);
const y = useSharedValue(0);
const pan = Gesture.Pan()
.onUpdate((e) => { x.value = e.translationX; y.value = e.translationY; })
.onEnd((e) => {
if (Math.abs(e.translationX) > width * 0.3) {
const direction = e.translationX > 0 ? "right" : "left";
x.value = withTiming(Math.sign(e.translationX) * width * 1.5, { duration: 200 }, (finished) => {
if (finished) scheduleOnRN(onSwipe, direction); // React 상태에서 카드 제거
});
} else {
x.value = withSpring(0);
y.value = withSpring(0);
}
});
const style = useAnimatedStyle(() => ({
transform: [{ translateX: x.value }, { translateY: y.value }, { rotate: `${interpolate(x.value, [-width, 0, width], [-15, 0, 15])}deg` }],
}));
return (
<GestureDetector gesture={pan}>
<Animated.View style={style}>{children}</Animated.View>
</GestureDetector>
);
}
결과: 카드가 손가락을 따라 움직이며 최대 15°까지 기울어집니다. 화면 너비의 30% 이상 벗어나서 놓으면 카드가 날아가고 JS 스레드에서 onSwipe("left" | "right")가 실행됩니다. 그렇지 않으면 중앙으로 다시 튕겨져 돌아옵니다.
예제 2: 애니메이션 바텀 시트
사용자 프롬프트: "드래그하여 올리고 특정 위치에 스냅되는 바텀 시트를 만들어 주세요."
// components/BottomSheet.tsx
import Animated, { useAnimatedStyle, useSharedValue, withSpring } from "react-native-reanimated";
import { Gesture, GestureDetector } from "react-native-gesture-handler";
import { useWindowDimensions } from "react-native";
import type { ReactNode } from "react";
export function BottomSheet({ children }: { children: ReactNode }) {
const { height } = useWindowDimensions();
const snapPoints = [height * 0.1, height * 0.5, height * 0.85]; // 위쪽 가장자리: 열림, 반, 미리보기
const top = useSharedValue(snapPoints[2]);
const start = useSharedValue(0);
const pan = Gesture.Pan()
.onBegin(() => { start.value = top.value; })
.onUpdate((e) => { top.value = Math.max(snapPoints[0], start.value + e.translationY); })
.onEnd((e) => {
const projected = top.value + e.velocityY * 0.2; // 플링이 도달할 예상 위치
const target = snapPoints.reduce((a, b) => (Math.abs(b - projected) < Math.abs(a - projected) ? b : a));
top.value = withSpring(target, { velocity: e.velocityY });
});
const style = useAnimatedStyle(() => ({ transform: [{ translateY: top.value }] }));
const sheet = { position: "absolute", left: 0, right: 0, top: 0, height, backgroundColor: "white" } as const;
return (
<GestureDetector gesture={pan}>
<Animated.View style={[sheet, style]}>{children}</Animated.View>
</GestureDetector>
);
}
결과: 시트가 미리보기 위치에서 시작하여 드래그를 따라 움직이고, 놓으면 세 개의 스냅 지점 중 가장 가까운 곳으로 플링 속도를 고려하여 튕겨져 이동합니다.
지침
- 애니메이션 상태에 공유 값 사용 —
useSharedValue는 UI 스레드에 상주하며, 값을 변경해도 컴포넌트가 다시 렌더링되지 않습니다. - 동적 스타일에
useAnimatedStyle사용 — UI 스레드에서 다시 계산됩니다. - 자연스러운 움직임에는
withSpring— 정확한 지속 시간이 필요하면withTiming을 사용하십시오. 버전 4는 스프링 기본값(댐핑 120, 강성 900)을 변경했으며duration을 인지적(perceptual)으로 처리합니다.Reanimated3DefaultSpringConfig를 사용하면 이전 느낌으로 복원할 수 있습니다. - 워크렛에서 JS 호출 시
scheduleOnRN사용 — 컴포넌트 또는 모듈 범위에서 정의된 함수를 전달하고, 워크렛 내부에서 생성된 함수는 전달하지 마십시오. - 제스처 핸들러 통합 —
Gesture.Pan(),Gesture.Pinch()등을 사용하며, 인라인으로 전달된 콜백은 자동으로 워크렛화되지만, 변수에 저장된 콜백은'worklet';지시문이 필요합니다. - 레이아웃 애니메이션은 선언적 — Animated 컴포넌트에
entering,exitingprops를 사용합니다. - 값 매핑에
interpolate사용 — 스크롤 위치를 opacity, scale 등에 매핑하고, 범위 끝에서 멈추려면Extrapolation.CLAMP를 전달합니다. - Worklets Babel 플러그인은 마지막에 위치 — Babel 구성을 변경한 후에는 Metro 캐시를 지우십시오.
- 워크렛에서 큰 객체 캡처 금지 — 캡처된 값은 UI 런타임에 복사됩니다. 공유 값, 프리미티브, 작은 일반 객체만 전달하십시오.
- 3.x에서 업그레이드 — 먼저 새로운 아키텍처를 활성화하고,
react-native-worklets를 설치하고, Babel 플러그인 이름을 변경한 후, 제거된useAnimatedGestureHandler,useWorkletCallback,combineTransition을 대체하십시오. - 사용하지 말아야 할 때 — 한 번만 실행되는 fade나 slide가 절대 블로킹되지 않는다면 React Native 내장
AnimatedAPI를 그대로 사용해도 됩니다 (네이티브 CSS 전환은 Reanimated 자체에서 제공). Reanimated 4는 기존 아키텍처를 사용하는 앱에 설치할 수 없습니다.