React View Transitions

ブラウザのネイティブな document.startViewTransition を使用して UI 状態間でアニメーション化します。<ViewTransition> で「何を」宣言し、startTransition/useDeferredValue/Suspense で「いつ」トリガーし、CSS クラスで「どのように」制御します。未対応ブラウザはアニメーションをスキップします。

アニメーション化するタイミング

すべての <ViewTransition> は、空間的な関係性または連続性を伝える必要があります。それが何を伝えるのか説明できない場合は、追加しないでください。

以下のリストからすべての該当するパターンを、この順序で実装します:

優先度	パターン	伝えるもの
1	共有要素 (name)	「同じもの — より深く進む」
2	Suspense reveal	「データが読み込まれた」
3	リスト認識 (アイテムごとの key)	「同じアイテム、新しい配列」
4	状態変更 (enter/exit)	「何かが表示/非表示になった」
5	ルート変更 (レイアウトレベル)	「新しい場所に移動する」

これは実装順序であり、「1 つ選ぶ」リストではありません。アプリに当てはまるすべてのパターンを実装します。そのアプリに使用例がない場合のみ、パターンをスキップします。

アニメーションスタイルの選択

コンテキスト	アニメーション	理由
階層的ナビゲーション(リスト → 詳細)	タイプキー付き nav-forward / nav-back	空間的な深さを伝える
横方向ナビゲーション(タブ間)	素の <ViewTransition>(フェード)または default="none"	深さを伝えない
Suspense reveal	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 をステップバイステップで従ってください。 監査から始めてください — スキップしないでください。references/css-recipes.md から CSS レシピをグローバルスタイルシートにコピーします — 独自のアニメーション 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 が同じトランジション中にマウントされる

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) — 出ていく + 入ってくるペア

すぐに使用できるアニメーションレシピについては、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 と互換性がありません)。代わりに明示的な URL で router.push() を使用します。

タイプと Suspense

タイプはナビゲーション中に利用可能ですが、その後の Suspense reveal 中には 利用できません(別個のトランジション、タイプなし)。ページレベルの enter/exit にはタイプマップを使用し、Suspense reveal には単純な文字列 props を使用します。

---

共有要素トランジション

2 つの VT に同じ name — 1 つはアンマウント、1 つはマウント — 共有要素モルフを作成します:

<ViewTransition name="hero-image">
  <img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
</ViewTransition>

// 他のビューで — 同じ名前
<ViewTransition name="hero-image">
  <img src="/full.jpg" />
</ViewTransition>

• 指定された name を持つ VT は一度に 1 つだけマウントできます — 一意の名前を使用します(photo-${id})。再利用可能なコンポーネントに注意してください: 名前付き VT を持つコンポーネントがモーダル/ポップオーバーとページの両方でレンダリングされる場合、両方が同時にマウントされ、モルフが壊れます。名前を条件付きにするか(prop 経由)、名前付き 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 で Re-Enter を強制する

<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
  <ResultsGrid />
</ViewTransition>

注意: <Suspense> をラップしている場合、key を変更すると境界がリマウントされ、再フェッチされます。

Suspense フォールバックをコンテンツに

シンプルなクロスフェード:

<ViewTransition>
  <Suspense fallback={<Skeleton />}><Content /></Suspense>
</ViewTransition>

方向性のある reveal:

<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
  <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
</Suspense>

詳細なパターンについては、references/patterns.md を参照してください。

---

複数の VT の相互作用

トリガーにマッチするすべての VT は単一の document.startViewTransition で同時に発火します。異なるトランジション(ナビゲーション対後続の Suspense 解決)内の VT は競合しません。

default="none" を自由に使用する

これがないと、すべての VT はすべてのトランジション(Suspense 解決、useDeferredValue アップデート、バックグラウンド再検証)でブラウザクロスフェードを発火します。常に default="none" を使用し、明示的に望ましいトリガーのみを有効にします。

2 つのパターンが共存する

パターン A — 方向性のあるスライド: 各ページのタイプキー付き VT、ナビゲーション中に発火。 パターン B — Suspense reveal: シンプルな文字列 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