React View Transitions

Animate between UI states using the browser's native document.startViewTransition. Declare what with <ViewTransition>, trigger when with startTransition / useDeferredValue / Suspense, control how with CSS classes. Unsupported browsers skip animations gracefully.

When to Animate

Every <ViewTransition> should communicate a spatial relationship or continuity. If you can't articulate what it communicates, don't add it.

Implement all applicable patterns from this list, in this order:

This is an implementation order, not a "pick one" list. Implement every pattern that fits the app. Only skip a pattern if the app has no use case for it.

Choosing Animation Style

Reserve directional slides for hierarchical navigation (list → detail) and ordered sequences (prev/next photo, carousel, paginated results). For ordered sequences, the direction communicates position: "next" slides from right, "previous" from left. Lateral/unordered navigation (tab-to-tab) should not use directional slides — it falsely implies spatial depth.

Availability

• Next.js: Do not install react@canary — the App Router already bundles React canary internally. ViewTransition works out of the box. npm ls react may show a stable-looking version; this is expected.
• Without Next.js: Install react@canary react-dom@canary (ViewTransition is not in stable React).
• Browser support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.

Core Concepts

The <ViewTransition> Component

import { ViewTransition } from "react";

<ViewTransition>
  <Component />
</ViewTransition>;

React auto-assigns a unique view-transition-name and calls document.startViewTransition behind the scenes. Never call startViewTransition yourself.

Animation Triggers

Only startTransition, useDeferredValue, or Suspense activate VTs. Regular setState does not animate.

Critical Placement Rule

<ViewTransition> only activates enter/exit if it appears before any DOM nodes:

// Works
<ViewTransition enter="auto" exit="auto">
  <div>Content</div>
</ViewTransition>

// Broken — div wraps the VT, suppressing enter/exit
<div>
  <ViewTransition enter="auto" exit="auto">
    <div>Content</div>
  </ViewTransition>
</div>

Behaviour is controlled with props ("auto" / "none" / a CSS class / a type-keyed object) and CSS pseudo-elements. See references/patterns.md for the full prop/pseudo-element reference, transition types, shared elements, and the multi-VT interaction rules.

Accessibility

Always add the reduced motion CSS from references/css-recipes.md to your global stylesheet.

Implementation Workflow

When adding view transitions to an existing app, follow references/implementation.md step by step. Start with the audit — do not skip it. Copy the CSS recipes from references/css-recipes.md into the global stylesheet — do not write your own animation CSS.

References

Each file is loaded on demand — read one only when the task needs that depth (progressive disclosure).

• references/implementation.md — step-by-step workflow for adding VTs to an app (audit → CSS → persistent elements → directional page transitions → Suspense reveals → shared elements → verify), plus common mistakes · read when starting an integration.
• references/patterns.md — the deep API and pattern catalogue: styling props + CSS pseudo-elements, transition types (addTransitionType, type maps, router.back() caveat), shared element morphs, the core composition patterns (enter/exit, list reorder, composing shared + list identity, force re-enter with key, Suspense reveals), how multiple VTs interact, plus worked patterns (deferred grid, card expand/collapse, type-safe helpers, cross-fade without remount, isolating elements, useOptimistic), events API, animation timing, and troubleshooting · read when implementing or debugging a specific behaviour.
• references/css-recipes.md — ready-to-use CSS animation recipes (timing variables, fade, slide, directional nav, shared/text morph, scale, persistent element isolation, reduced motion) · read when writing the global stylesheet.
• references/nextjs.md — Next.js App Router specifics: experimental.viewTransition flag, transitionTypes on next/link, programmatic navigation, server-side filtering, loading.tsx boundaries, same-route dynamic segments, Server Components · read when integrating in Next.js.