vercel-react-view-transitions

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:

Priority	Pattern	What it communicates
1	Shared element (name)	"Same thing — going deeper"
2	Suspense reveal	"Data loaded"
3	List identity (per-item key)	"Same items, new arrangement"
4	State change (enter/exit)	"Something appeared/disappeared"
5	Route change (layout-level)	"Going to a new place"

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

Context	Animation	Why
Hierarchical navigation (list → detail)	Type-keyed nav-forward / nav-back	Communicates spatial depth
Lateral navigation (tab-to-tab)	Bare <ViewTransition> (fade) or default="none"	No depth to communicate
Suspense reveal	enter/exit string props	Content arriving
Revalidation / background refresh	default="none"	Silent — no animation needed

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 a compatible React version internally. The official docs still require experimental.viewTransition: true for Next.js integration and mark it experimental; verify the installed version's docs/source before relying on it in production (see references/nextjs.md).
• Without Next.js: Install react@canary react-dom@canary (ViewTransition is not in stable React). <ViewTransition> and addTransitionType are only available in React's Canary and Experimental channels — not in stable React 19.2.
• TypeScript: @types/react declares ViewTransition and addTransitionType in canary.d.ts, not in index.d.ts, so a project using the stable types fails to compile with Module '"react"' has no exported member 'ViewTransition' even though Next.js has swapped in a React build that exports them at runtime. Point the compiler at the shipped declarations — do not hand-write a module augmentation, the accurate ones are already in the package: