---
id: react-animation-performance
title: React 애니메이션 — GPU 가속과 CSS 우선
category: Coding
status: draft
source_trust_level: B
verification_status: conceptual
created_at: 2026-05-09
updated_at: 2026-05-09
tags: [react, animation, performance, transform, vibe-coding]
tech_stack: { language: "TypeScript / Framer Motion / CSS", applicable_to: ["Web"] }
applied_in: []
aliases: [transform, will-change, requestAnimationFrame, framer-motion]
---

# React 애니메이션 성능

> 60fps 의 비밀: **transform / opacity 만 애니메이션**. width / height / top / left 는 layout/paint trigger → jank. JS 로 setState 매 frame 도 안 됨.

## 📖 핵심 개념
- 브라우저 렌더 단계: JS → Style → Layout → Paint → Composite.
- transform/opacity 는 Composite 만 쓰는 GPU layer — 다른 단계 skip.
- React setState per frame = re-render 60회/초. 컴포넌트 트리에 따라 폭발.

## 💻 코드 패턴

### CSS 우선
```css
.modal {
  transform: translateY(100%);
  opacity: 0;
  transition: transform 200ms ease-out, opacity 200ms ease-out;
}
.modal.open { transform: translateY(0); opacity: 1; }
```

### Framer Motion — declarative
```tsx
import { motion, AnimatePresence } from 'framer-motion';

<AnimatePresence>
  {open && (
    <motion.div
      initial={{ y: 100, opacity: 0 }}
      animate={{ y: 0, opacity: 1 }}
      exit={{ y: 100, opacity: 0 }}
      transition={{ type: 'spring', stiffness: 300, damping: 30 }}
    >
      ...
    </motion.div>
  )}
</AnimatePresence>
```

### 직접 ref + transform — React state 우회
```tsx
function DragBox() {
  const ref = useRef<HTMLDivElement>(null);
  useEffect(() => {
    const onMove = (e: MouseEvent) => {
      // setState X — DOM 직접
      if (ref.current) ref.current.style.transform = `translate(${e.clientX}px, ${e.clientY}px)`;
    };
    window.addEventListener('mousemove', onMove);
    return () => window.removeEventListener('mousemove', onMove);
  }, []);
  return <div ref={ref} />;
}
```

### will-change — 신중히
```css
.about-to-animate { will-change: transform; }
/* 애니메이션 끝나면 제거. 영구 두면 메모리 부담 */
```

## 🤔 의사결정 기준
| 효과 | 도구 |
|---|---|
| 단순 hover / focus | CSS transition |
| 복잡 enter/exit + spring | Framer Motion |
| Drag / gesture | react-use-gesture + useSpring 또는 useMotionValue |
| Canvas / WebGL | requestAnimationFrame + 별도 라이브러리 (three.js) |
| 프레임 단위 React state | ❌ — DOM 직접 또는 motion value |

## ❌ 안티패턴
- **width/height/top/left 애니메이션**: layout thrash. transform: scale / translate 로.
- **per-frame setState**: 컴포넌트 트리 재렌더. ref + DOM 직접 또는 motion.
- **will-change 영구 적용**: GPU 메모리. 애니메이션 시작 직전 추가, 끝나면 제거.
- **거대 list 모두에 transition**: 스크롤 시 60fps 깨짐. visible 영역만.
- **가속도 무한**: spring 계산 안 멈춤 → CPU. damping ≥ 10 권장.
- **React.memo 없는 자식이 부모 animation state 받음**: 매 frame 재렌더.
- **resize observer 안에 무거운 작업**: throttle / debounce.

## 🤖 LLM 활용 힌트
- "transform / opacity 만 애니메이션. layout 속성 금지" 강조.
- per-frame 작업은 useRef + DOM 직접.

## 🔗 관련 문서
- [[React_Rendering_Optimization]]
- [[React_Refs_Patterns]]