React View Transitions
document.startViewTransition을 사용하여 UI 상태 간 애니메이션을 구현합니다. 무엇을 <ViewTransition>으로 선언하고, 언제 startTransition / useDeferredValue / Suspense로 트리거하며, 어떻게 CSS 클래스로 제어합니다. 지원하지 않는 브라우저에서는 애니메이션이 부드럽게 생략됩니다.
애니메이션 적용 시점
모든 <ViewTransition>은 공간적 관계나 연속성을 전달해야 합니다. 무엇을 전달하는지 명확히 설명할 수 없다면 추가하지 마세요.
다음 목록에서 모든 적용 가능한 패턴을 우선순위 순서대로 구현하세요:
| 우선순위 | 패턴 | 전달하는 의미 |
|---|---|---|
| 1 | 공유 요소 (name) | "같은 것, 더 깊이 들어감" |
| 2 | Suspense 공개 | "데이터 로드됨" |
| 3 | 리스트 식별 (항목별 key) | "같은 항목, 새 배열" |
| 4 | 상태 변경 (enter/exit) | "무언가 나타남/사라짐" |
| 5 | 경로 변경 (레이아웃 수준) | "새로운 장소로 이동" |
이는 "하나만 선택" 목록이 아닌 구현 순서입니다. 앱에 맞는 모든 패턴을 구현하세요. 앱에 해당 패턴의 사용 사례가 없는 경우에만 건너뜁니다.
애니메이션 스타일 선택
| 상황 | 애니메이션 | 이유 |
|---|---|---|
| 계층적 내비게이션 (목록 → 상세) | 타입 기반 nav-forward / nav-back | 공간적 깊이 전달 |
| 수평적 내비게이션 (탭 간) | 기본 <ViewTransition> (페이드) 또는 default="none" | 전달할 깊이 없음 |
| Suspense 공개 | enter/exit 문자열 props | 콘텐츠 도착 |
| 재검증 / 백그라운드 새로고침 | default="none" | 조용히, 애니메이션 불필요 |
방향형 슬라이드는 계층적 내비게이션(목록→상세)과 순서 있는 시퀀스(이전/다음 사진, 캐러셀, 페이지네이션 결과)에 한정하세요. 순서 있는 시퀀스의 경우 방향이 위치를 전달합니다: "다음"은 오른쪽에서 슬라이드, "이전"은 왼쪽에서 슬라이드. 수평적/비순서형 내비게이션(탭 간)에는 방향형 슬라이드를 사용하지 마세요. 이는 공간적 깊이를 잘못 암시합니다.
지원 환경
- Next.js:
react@canary를 설치하지 마세요: App Router는 이미 내부적으로 React canary를 번들로 제공합니다.ViewTransition이 기본적으로 동작합니다.npm ls react가 안정적인 버전처럼 보일 수 있으나 이는 정상입니다. - Next.js 없이:
react@canary react-dom@canary를 설치하세요 (ViewTransition은 안정적인 React에 포함되지 않음). - 브라우저 지원: Chromium 111+, Firefox 144+, Safari 18.2+. 지원하지 않는 브라우저에서는 우아하게 대체됩니다.
구현 워크플로우
기존 앱에 뷰 전환을 추가할 때는 references/implementation.md를 단계별로 따르세요. 감사(audit)부터 시작하고 건너뛰지 마세요. references/css-recipes.md의 CSS 레시피를 전역 스타일시트에 복사하고, 직접 애니메이션 CSS를 작성하지 마세요.
핵심 개념
<ViewTransition> 컴포넌트
import { ViewTransition } from 'react';
<ViewTransition>
<Component />
</ViewTransition>
React가 고유한 view-transition-name을 자동으로 할당하고 내부적으로 document.startViewTransition을 호출합니다. 절대 직접 startViewTransition을 호출하지 마세요.
애니메이션 트리거
| 트리거 | 발생 시점 |
|---|---|
| enter | <ViewTransition>이 Transition 중에 처음 삽입될 때 |
| exit | <ViewTransition>이 Transition 중에 처음 제거될 때 |
| update | <ViewTransition> 내부의 DOM 변경. 중첩 VT가 있으면 가장 안쪽 VT에 적용됨 |
| share | 이름이 지정된 VT가 마운트 해제되고 같은 name을 가진 다른 VT가 같은 Transition 중에 마운트될 때 |
startTransition, useDeferredValue 또는 Suspense만 VT를 활성화합니다. 일반 setState는 애니메이션을 트리거하지 않습니다.
중요한 배치 규칙
<ViewTransition>은 어떤 DOM 노드보다 먼저 나타나야 enter/exit를 활성화합니다:
// 정상 동작
<ViewTransition enter="auto" exit="auto">
<div>Content</div>
</ViewTransition>
// 오류 발생, div가 VT를 감싸서 enter/exit가 억제됨
<div>
<ViewTransition enter="auto" exit="auto">
<div>Content</div>
</ViewTransition>
</div>
뷰 전환 클래스로 스타일링
Props
값: "auto" (브라우저 크로스페이드), "none" (비활성화), "class-name" (사용자 정의 CSS), 또는 { [type]: value } (타입별 애니메이션).
<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
default가 "none"이면 명시적으로 나열된 경우를 제외하고 모든 트리거가 꺼집니다.
CSS 의사 요소
::view-transition-old(.class): 나가는 스냅샷::view-transition-new(.class): 들어오는 스냅샷::view-transition-group(.class): 컨테이너::view-transition-image-pair(.class): old + new 쌍
바로 사용할 수 있는 애니메이션 레시피는 references/css-recipes.md를 참조하세요.
전환 유형(Transition Types)
addTransitionType으로 전환에 태그를 지정하면 VT가 컨텍스트에 따라 다른 애니메이션을 선택할 수 있습니다. 여러 번 호출하여 유형을 쌓을 수 있으며, 트리 내의 다른 VT가 다른 유형에 반응합니다:
startTransition(() => {
addTransitionType('nav-forward');
addTransitionType('select-item');
router.push('/detail/1');
});
객체를 전달하여 유형을 CSS 클래스에 매핑합니다. enter, exit, 그리고 share에서 모두 작동합니다:
<ViewTransition
enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
default="none"
>
<Page />
</ViewTransition>
enter와 exit가 대칭일 필요는 없습니다. 예를 들어, 페이드 인하지만 방향성 슬라이드 아웃:
<ViewTransition
enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
default="none"
>
TypeScript: ViewTransitionClassPerType는 객체에 default 키를 요구합니다.
여러 페이지가 있는 앱의 경우 타입 기반 VT를 재사용 가능한 래퍼로 추출하세요:
export function DirectionalTransition({ children }: { children: React.ReactNode }) {
return (
<ViewTransition
enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
default="none"
>
{children}
</ViewTransition>
);
}
router.back() 및 브라우저 뒤로 가기 버튼
router.back()과 브라우저의 뒤로/앞으로 가기 버튼은 뷰 전환을 트리거하지 않습니다 (popstate는 동기식이며 startViewTransition과 호환되지 않음). 대신 명시적인 URL과 함께 router.push()를 사용하세요.
유형과 Suspense
유형은 내비게이션 중에는 사용 가능하지만 이후 Suspense 공개 중에는 사용할 수 없습니다 (별도의 전환, 유형 없음). 페이지 수준의 enter/exit에는 유형 맵을 사용하고, Suspense 공개에는 간단한 문자열 props를 사용하세요.
공유 요소 전환
동일한 name을 가진 두 VT(하나는 마운트 해제, 하나는 마운트)는 공유 요소 변환(morph)을 생성합니다:
<ViewTransition name="hero-image">
<img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
</ViewTransition>
// 다른 뷰에서, 동일한 name
<ViewTransition name="hero-image">
<img src="/full.jpg" />
</ViewTransition>
- 주어진
name을 가진 VT는 한 번에 하나만 마운트될 수 있습니다. 고유한 이름(photo-${id})을 사용하세요. 재사용 가능한 컴포넌트에 주의하세요: 이름이 지정된 VT가 있는 컴포넌트가 모달/팝오버 그리고 페이지 모두에서 렌더링되면 둘 다 동시에 마운트되어 변환이 깨집니다. 이름을 조건부로 만들거나(prop을 통해), 공유 컴포넌트에서 이름이 지정된 VT를 제거하고 특정 소비자로 이동하세요. share는enter/exit보다 우선합니다. 각 내비게이션 경로를 신중히 고려하세요: 일치하는 쌍이 형성되지 않으면(예: 대상 페이지에 동일한 name이 없음)enter/exit가 대신 실행됩니다. 해당 경로에 대한 대체 애니메이션이 필요한지 고려하세요.- 공유 모프가 있는 페이지에서 페이드 아웃 종료를 사용하지 마세요. 대신 방향성 슬라이드를 사용하세요.
일반적인 패턴
Enter/Exit
{show && (
<ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
)}
리스트 재정렬
{items.map(item => (
<ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
))}
startTransition 내에서 트리거합니다. 리스트와 VT 사이에 래퍼 <div>를 피하세요.
공유 요소와 리스트 식별 결합
공유 요소와 리스트 식별은 독립적인 개념이므로 서로 혼동하지 마세요. 리스트 항목에 공유 요소(예: 상세 뷰로 변환되는 이미지)가 포함된 경우 두 개의 중첩된 <ViewTransition> 경계를 사용하세요:
{items.map(item => (
<ViewTransition key={item.id}> {/* 리스트 식별 */}
<Link href={`/items/${item.id}`}>
<ViewTransition name={`item-image-${item.id}`} share="morph"> {/* 공유 요소 */}
<Image src={item.image} />
</ViewTransition>
<p>{item.name}</p>
</Link>
</ViewTransition>
))}
외부 VT는 리스트 재정렬/입력 애니메이션을 처리합니다. 내부 VT는 경로 간 공유 요소 모프를 처리합니다. 어느 한 레이어가 없으면 해당 애니메이션이 조용히 실행되지 않습니다.
key로 강제 재진입
<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
<ResultsGrid />
</ViewTransition>
주의: <Suspense>를 감싸는 경우 key를 변경하면 경계가 다시 마운트되어 데이터를 다시 가져옵니다.
Suspense Fallback에서 콘텐츠로
단순 크로스페이드:
<ViewTransition>
<Suspense fallback={<Skeleton />}><Content /></Suspense>
</ViewTransition>
방향성 공개:
<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
<ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
</Suspense>
더 많은 패턴은 references/patterns.md를 참조하세요.
여러 VT 간의 상호 작용
트리거와 일치하는 모든 VT는 하나의 document.startViewTransition에서 동시에 실행됩니다. 다른 전환(내비게이션 vs 이후 Suspense 해결)에 있는 VT는 서로 경쟁하지 않습니다.
default="none"을 자유롭게 사용하세요
이 값이 없으면 모든 VT가 모든 전환에서 브라우저 크로스페이드를 실행합니다: Suspense 해결, useDeferredValue 업데이트, 백그라운드 재검증. 항상 default="none"을 사용하고 원하는 트리거만 명시적으로 활성화하세요.
두 패턴 공존
패턴 A. 방향성 슬라이드: 각 페이지에 타입 기반 VT, 내비게이션 중 실행. 패턴 B. Suspense 공개: 간단한 문자열 props, 데이터 로드 시 실행 (유형 없음).
두 패턴은 서로 다른 시점에 실행되므로 공존할 수 있습니다. 두 패턴 모두 default="none"이 적용되어 상호 간섭을 방지합니다. 항상 enter와 exit를 쌍으로 사용하세요. 방향성 VT는 페이지 컴포넌트에 배치하고 레이아웃에는 배치하지 마세요.
중첩 VT 제한
부모 VT가 종료되면 내부의 중첩 VT는 자체 enter/exit를 실행하지 않습니다. 가장 바깥쪽 VT만 애니메이션됩니다. 페이지 내비게이션 중 항목별 지연 애니메이션은 현재 불가능합니다. 실험적 옵트인 수정 사항은 react#36135를 참조하세요.
Next.js 통합
Next.js 설정 방법 (experimental.viewTransition 플래그, next/link의 transitionTypes prop, App Router 패턴, 서버 컴포넌트)은 references/nextjs.md를 참조하세요.
접근성
references/css-recipes.md의 축소 모션 CSS를 항상 전역 스타일시트에 추가하세요.
참조 파일
references/implementation.md: 단계별 구현 워크플로우.references/patterns.md: 패턴, 애니메이션 타이밍, 이벤트 API, 문제 해결.references/css-recipes.md: 바로 사용할 수 있는 CSS 애니메이션 레시피.references/nextjs.md: Next.js App Router 패턴 및 서버 컴포넌트 세부 정보.
전체 컴파일된 문서
모든 참조 파일이 확장된 전체 가이드는 AGENTS.md를 참조하세요.
