React View Transitions (React画面遷移アニメーション)
ブラウザネイティブの document.startViewTransition を使用して、UI状態間のアニメーションを実現します。アニメーション対象を <ViewTransition> で宣言し、startTransition / useDeferredValue / Suspense で発火タイミングを制御し、CSSクラスでアニメーションの詳細を指定します。非対応ブラウザではアニメーションは自動的にスキップされ、問題なく動作します。
アニメーションを適用するタイミング
すべての <ViewTransition> は、空間的な関係性や連続性を伝えるために使用する必要があります。「このアニメーションは何を伝えるのか」を明確に説明できない場合は、追加すべきではありません。
以下のリストから、該当するすべてのパターン をこの優先順位で実装してください:
| 優先度 | パターン | 伝える内容 |
|---|---|---|
| 1 | 共有要素 (name) | 「同じものが、より深い階層へ」 |
| 2 | Suspense表示 | 「データが読み込まれた」 |
| 3 | リスト識別 (要素ごとの key) | 「同じアイテム、新しい配置」 |
| 4 | 状態変化 (enter/exit) | 「何かが現れた/消えた」 |
| 5 | ルート変更 (レイアウトレベル) | 「新しい場所へ移動」 |
これは「1つを選ぶ」リストではなく、実装順序を示しています。アプリに適合するすべてのパターンを実装してください。アプリにユースケースがない場合のみ、そのパターンをスキップします。
アニメーションスタイルの選択
| コンテキスト | アニメーション | 理由 |
|---|---|---|
| 階層的ナビゲーション(リスト→詳細) | タイプ指定 nav-forward / nav-back | 空間的な奥行きを伝える |
| 横方向ナビゲーション(タブ切り替え) | ベアな <ViewTransition> (フェード) または default="none" | 奥行きを伝える必要がない |
| Suspense表示 | enter/exit 文字列プロップ | コンテンツの到着 |
| 再検証 / バックグラウンド更新 | 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)から始め、スキップしないでください。CSSレシピは references/css-recipes.md からコピーしてグローバルスタイルシートに追加し、独自のアニメーションCSSは記述しないでください。
中核概念
<ViewTransition> コンポーネント
import { ViewTransition } from 'react';
<ViewTransition>
<Component />
</ViewTransition>
Reactが自動で一意の view-transition-name を割り当て、内部で document.startViewTransition を呼び出します。startViewTransition を自分で呼び出さないでください。
アニメーションの発火トリガー
| トリガー | 発火タイミング |
|---|---|
| enter | トランジション中に <ViewTransition> が初めて挿入されたとき |
| exit | トランジション中に <ViewTransition> が初めて削除されたとき |
| update | <ViewTransition> 内部のDOMが変更されたとき。ネストされたVTの場合、最も内側のVTに適用される |
| share | 名前付きVTがアンマウントされ、同じ name を持つ別のVTが同じトランジション内でマウントされたとき |
VTを有効化するのは startTransition、useDeferredValue、Suspense のみです。通常の setState ではアニメーションは発生しません。
配置ルール(重要)
<ViewTransition> は、すべてのDOMノードより前に配置 されている場合にのみ enter/exit を有効化します:
// 動作する
<ViewTransition enter="auto" exit="auto">
<div>コンテンツ</div>
</ViewTransition>
// 動作しない:divがVTをラップしているため、enter/exitが抑制される
<div>
<ViewTransition enter="auto" exit="auto">
<div>コンテンツ</div>
</ViewTransition>
</div>
ビュートランジションクラスを使ったスタイリング
プロップ
値: "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 を参照してください。
トランジションタイプ
トランジションに 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 と互換性がありません)。代わりに router.push() に明示的なURLを指定して使用してください。
タイプとSuspense
タイプはナビゲーション中に利用できますが、その後のSuspense表示中は利用できません(別個のトランジションであり、タイプは引き継がれません)。ページレベルのenter/exitにはタイプマップを使用し、Suspense表示には単純な文字列プロップを使用してください。
共有要素トランジション
2つのVTが同じ name を持ち、片方がアンマウントされもう片方がマウントされると、共有要素のモーフィングが発生します:
<ViewTransition name="hero-image">
<img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
</ViewTransition>
// 別のビューで、同じname
<ViewTransition name="hero-image">
<img src="/full.jpg" />
</ViewTransition>
- 特定の
nameを持つVTは同時に1つしかマウントできません。一意の名前を使用してください(photo-${id})。再利用可能なコンポーネントに注意:名前付きVTを持つコンポーネントがモーダル/ポップオーバーおよび ページの両方でレンダリングされると、両方が同時にマウントされモーフィングが破綻します。名前を条件付きにする(プロップ経由)か、名前付きVTを共有コンポーネントから特定のコンシューマーに移動してください。 shareはenter/exitよりも優先されます。各ナビゲーションパスを考慮してください:一致するペアが形成されない場合(例:遷移先ページに同じ名前がない場合)、代わりにenter/exitが発火します。そのパスにおけるフォールバックアニメーションが必要かどうかを検討してください。- 共有モーフを含むページでフェードアウトの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> を置かないでください。
リスト識別と共有要素の組み合わせ
共有要素とリスト識別は独立した関心事であり、混同しないでください。リストアイテムに共有要素(例:詳細ビューにモーフィングする画像)が含まれる場合は、2つのネストされた <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はリストの並び替え/enterアニメーションを処理します。内側のVTはルート間の共有要素モーフィングを処理します。どちらかのレイヤーが欠けていると、そのアニメーションは静かに実行されません。
key による強制再Enter
<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
<ResultsGrid />
</ViewTransition>
注意: <Suspense> をラップする場合、key を変更するとバウンダリーが再マウントされ、データが再取得されます。
Suspenseのフォールバックからコンテンツへ
シンプルなクロスフェード:
<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" を使用し、必要なトリガーのみを明示的に有効にしてください。
2つのパターンは共存する
パターンA. 方向性スライド: 各ページのタイプキー付きVT。ナビゲーション中に発火します。 パターンB. Suspense表示: 単純な文字列プロップ。データ読み込み時に発火します(タイプなし)。
これらは異なるタイミングで発火するため共存できます。両方に default="none" を設定することで相互干渉を防ぎます。常に enter と exit をペアで指定してください。方向性VTはページコンポーネントに配置し、レイアウトには配置しないでください。
ネストされたVTの制限
親VTがexitするとき、その内部のネストされたVTは自身のenter/exitを発火しません。最も外側のVTのみがアニメーションします。現在のところ、ページナビゲーション中にアイテムごとにずらしたアニメーションを実現することはできません。実験的なオプトイン修正については react#36135 を参照してください。
Next.js 連携
Next.jsのセットアップ(experimental.viewTransition フラグ、next/link の transitionTypes プロップ、App Routerパターン、サーバーコンポーネント)については、references/nextjs.md を参照してください。
アクセシビリティ
references/css-recipes.md から「動きの低減」(reduced motion)CSSを必ずグローバルスタイルシートに追加してください。
参照ファイル
references/implementation.md: ステップバイステップの実装ワークフロー。references/patterns.md: パターン、アニメーションのタイミング、イベントAPI、トラブルシューティング。references/css-recipes.md: すぐに使えるCSSアニメーションレシピ。references/nextjs.md: Next.js App Router パターンとサーバーコンポーネントの詳細。
完全な統合ドキュメント
すべての参照ファイルを展開した完全なガイドについては:AGENTS.md
