accounted/.agents/skills/vercel-react-view-transitions/AGENTS.md

React View Transitions

Version 1.0.0 Vercel Engineering March 2026

Note: This document is mainly for agents and LLMs to follow when implementing view transitions in React applications. Humans may also find it useful, but guidance here is optimized for automation and consistency by AI-assisted workflows.

---

Abstract

Guide for implementing smooth, native-feeling animations using React's View Transition API. Covers the <ViewTransition> component, addTransitionType, CSS view transition pseudo-elements, shared element transitions, Suspense reveals, list reorder, directional navigation, and Next.js integration. Includes a step-by-step implementation workflow, ready-to-use CSS animation recipes, and common mistake warnings.

---

Table of Contents

1. Core Reference
   • When to Animate
   • Availability
   • Core Concepts
   • Styling with View Transition Classes
   • Transition Types
   • Shared Element Transitions
   • Common Patterns
   • How Multiple VTs Interact
   • Next.js Integration
   • Accessibility
2. Implementation Workflow
   • Step 1: Audit the App
   • Step 2: Add CSS Recipes
   • Step 3: Isolate Persistent Elements
   • Step 4: Add Directional Page Transitions
   • Step 5: Add Suspense Reveals
   • Step 6: Add Shared Element Transitions
   • Step 7: Verify Each Navigation Path
   • Common Mistakes
3. Patterns and Guidelines
4. CSS Animation Recipes
5. View Transitions in Next.js

---

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 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.

---

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

Trigger	When it fires
enter	VT first inserted during a Transition
exit	VT first removed during a Transition
update	DOM mutations inside a VT. With nested VTs, mutation applies to the innermost one
share	Named VT unmounts and another with same name mounts in same Transition

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

Critical Placement Rule

VT 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
<div><ViewTransition enter="auto" exit="auto"><div>Content</div></ViewTransition></div>

---

Styling with View Transition Classes

Values: "auto" (browser cross-fade), "none" (disabled), "class-name" (custom CSS), or { [type]: value } for type-specific animations.

<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />

If default is "none", all triggers are off unless explicitly listed.

CSS Pseudo-Elements

• ::view-transition-old(.class) — outgoing snapshot
• ::view-transition-new(.class) — incoming snapshot
• ::view-transition-group(.class) — container
• ::view-transition-image-pair(.class) — old + new pair

---

Transition Types

Tag transitions with addTransitionType so VTs can pick different animations. Call it multiple times to stack types — different VTs in the tree react to different types:

startTransition(() => {
  addTransitionType('nav-forward');
  addTransitionType('select-item');
  router.push('/detail/1');
});

Map types to CSS classes. Works on enter, exit, and 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 and exit don't have to be symmetric. For example, fade in but slide out directionally:

<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 requires a default key.

router.back() and Browser Back Button

router.back() and the browser's back/forward buttons do not trigger view transitions (popstate is synchronous, incompatible with startViewTransition). Use router.push() with an explicit URL instead.

Types and Suspense

Types are available during navigation but not during subsequent Suspense reveals (separate transitions, no type). Use type maps for page-level enter/exit; use simple string props for Suspense reveals.

---

Shared Element Transitions

Same name on two VTs — one unmounting, one mounting — creates a shared element morph:

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

// Other view — same name
<ViewTransition name="hero-image">
  <img src="/full.jpg" />
</ViewTransition>

• Only one VT with a given name can be mounted at a time — use unique names. Watch for reusable components: if a component with a named VT is rendered in both a modal/popover and a page, both mount simultaneously and break the morph. Either make the name conditional (via a prop) or move the named VT out of the shared component into the specific consumer.
• share takes precedence over enter/exit. Think through each navigation path: when no pair forms, enter/exit fires instead. Consider whether the element needs a fallback animation for those paths.
• Never use fade-out exit on pages with shared morphs — use directional slide.

---

Common Patterns

Enter/Exit

{show && (
  <ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
)}

List Reorder

{items.map(item => (
  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
))}

Trigger inside startTransition. Avoid wrapper <div>s between list and VT.

Composing Shared Elements with List Identity

Shared elements and list identity are independent concerns — don't confuse one for the other. When a list item contains a shared element, use two nested <ViewTransition> boundaries:

{items.map(item => (
  <ViewTransition key={item.id}>                                      {/* list identity */}
    <Link href={`/items/${item.id}`}>
      <ViewTransition name={`item-image-${item.id}`} share="morph">   {/* shared element */}
        <Image src={item.image} />
      </ViewTransition>
      <p>{item.name}</p>
    </Link>
  </ViewTransition>
))}

The outer VT handles list reorder/enter. The inner VT handles cross-route shared element morph. Missing either layer means that animation silently doesn't happen.

Force Re-Enter with key

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

Caution: Wrapping <Suspense> with key remounts the boundary and refetches.

Suspense Fallback to Content

Simple cross-fade:

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

Directional reveal:

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

---

How Multiple VTs Interact

Every VT matching the trigger fires simultaneously in a single document.startViewTransition. VTs in different transitions don't compete.

Use default="none" Liberally

Without it, every VT fires the browser cross-fade on every transition. Always use default="none" and explicitly enable only desired triggers.

Two Patterns Coexist

Pattern A — Directional slides: Type-keyed VT on each page, fires during navigation. Pattern B — Suspense reveals: Simple string props, fires when data loads (no type).

They coexist because they fire at different moments. default="none" on both prevents cross-interference. Always pair enter with exit. Place directional VTs in page components, not layouts.

Nested VT Limitation

When a parent VT exits, nested VTs inside it do not fire their own enter/exit — only the outermost VT animates. Per-item staggered animations during page navigation are not possible today. See react#36135 for an experimental opt-in fix.

---

Next.js Integration

See the View Transitions in Next.js section below.

---

Accessibility

Always add reduced motion CSS to your global stylesheet:

@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(*),
  ::view-transition-new(*),
  ::view-transition-group(*) {
    animation-duration: 0s !important;
    animation-delay: 0s !important;
  }
}

---

Implementation Workflow

Follow these steps in order. Start with the audit — do not skip it. Copy the CSS recipes from the CSS Recipes section below — do not write your own animation CSS.

Step 1: Audit the App

Before writing any code, scan the codebase thoroughly. Search for:

• Every <Link> and router.push — open every file that contains one
• Every <Suspense> boundary — check what its fallback renders
• Every page/route component — each needs a VT placement decision
• Persistent elements (headers, navbars, sidebars) — need viewTransitionName isolation
• Shared visual elements on both source and target views
• Skeleton-to-content control pairs — if a fallback renders a control that also exists in the real content, both need a matching viewTransitionName

Then classify every navigation and produce a navigation map:

| Route           | Navigates to         | Direction    | VT pattern            |
|-----------------|----------------------|--------------|-----------------------|
| /               | /detail/[id]         | forward      | directional slide     |
| /detail/[id]    | /                    | back         | directional slide     |
| /detail/[id]    | /detail/[other]      | sequential   | directional slide (ordered prev/next) or key+share crossfade |
| /tab/[a]        | /tab/[b]             | lateral      | key+share crossfade   |
| (Suspense)      | (content loads)      | —            | slide-up reveal       |

For each shared element (name prop), note where a pair forms and where it doesn't — this determines whether you need enter/exit as a fallback alongside share.

Step 2: Add CSS Recipes

Copy the complete CSS recipe set from the CSS Animation Recipes section below into your global stylesheet. Don't write your own — the recipes handle staggered timing, motion blur, and reduced motion.

Step 3: Isolate Persistent Elements

<header style={{ viewTransitionName: "site-header" }}>...</header>

::view-transition-group(site-header) {
  animation: none;
  z-index: 100;
}

For backdrop-blur/backdrop-filter, use the backdrop-blur workaround instead.

Step 4: Add Directional Page Transitions

startTransition(() => {
  addTransitionType('nav-forward');
  router.push('/detail/1');
});

Wrap each page component (not layout) in a type-keyed VT:

<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"
>
  <div>...page content...</div>
</ViewTransition>

Extract into a reusable component so every page doesn't repeat the type map:

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>
  );
}

Rules: Always pair enter with exit. Always include default: "none". Place in page components, not layouts. Only use directional slides for hierarchical navigation or ordered sequences (prev/next).

Step 5: Add Suspense Reveals

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

Use default="none" on content VT. Use simple string props (not type maps) — Suspense resolves have no type.

Step 6: Add Shared Element Transitions

// Source view
<ViewTransition name={`photo-${photo.id}`} share="morph" default="none">
  <Image src={photo.src} ... />
</ViewTransition>

// Target view — same name
<ViewTransition name={`photo-${photo.id}`} share="morph">
  <Image src={photo.src} ... />
</ViewTransition>

When list items contain shared elements, compose both patterns — two independent layers:

{items.map(item => (
  <ViewTransition key={item.id}>                                        {/* list identity */}
    <Link href={`/detail/${item.id}`}>
      <ViewTransition name={`item-${item.id}`} share="morph" default="none">  {/* shared element */}
        <Image src={item.image} ... />
      </ViewTransition>
    </Link>
  </ViewTransition>
))}

The outer VT handles list reorder/enter. The inner VT handles cross-route shared element morph. Missing either layer means that animation silently doesn't happen.

Rules: Names must be globally unique. Add default="none" on list-side shared elements.

Step 7: Verify Each Navigation Path

Walk through every row in the navigation map from Step 1:

• Does the VT mount/unmount, or stay mounted (same-route)?
• For named VTs: does a shared pair form? If not, does enter/exit provide a fallback?
• Does default="none" block an animation you actually want?
• Do persistent elements stay static?
• Do Suspense reveals animate independently from directional navigations?

---

Common Mistakes

• Bare VT without default="none" — fires cross-fade on every transition
• Directional VT in a layout — layouts persist, enter/exit won't fire on route changes
• Fade-out exit with shared morphs — conflicts with morph, use directional slide
• Writing custom animation CSS — use the recipes
• Missing default: "none" in type-keyed objects — TypeScript requires it, fallback is "auto"
• Type maps on Suspense reveals — Suspense resolves have no type, use string props
• Raw viewTransitionName CSS to trigger animations — React only starts view transitions when <ViewTransition> components are in the tree. Bare viewTransitionName is for isolating elements, not triggering animations.
• update trigger for same-route navigations — nested VTs steal the mutation from the parent. Use key + name + share instead.
• Named VT in a reusable component — if a component with a named VT is rendered in both a modal/popover and a page, both mount simultaneously and break the morph. Make the name conditional or move it to the specific consumer.
• router.back() for back navigation — router.back() triggers synchronous popstate, incompatible with view transitions. Use router.push() with an explicit URL.

For Next.js-specific steps, see the Next.js section below.

---

Patterns and Guidelines

Searchable Grid with useDeferredValue

'use client';

import { useDeferredValue, useState, ViewTransition, Suspense } from 'react';

export default function SearchableGrid({ itemsPromise }) {
  const [search, setSearch] = useState('');
  const deferredSearch = useDeferredValue(search);

  return (
    <>
      <input value={search} onChange={(e) => setSearch(e.currentTarget.value)} />
      <ViewTransition>
        <Suspense fallback={<GridSkeleton />}>
          <ItemGrid itemsPromise={itemsPromise} search={deferredSearch} />
        </Suspense>
      </ViewTransition>
    </>
  );
}

Per-item named VTs in deferred lists trigger cross-fades on every keystroke. Fix with default="none".

Card Expand/Collapse with startTransition

'use client';

import { useState, useRef, startTransition, ViewTransition } from 'react';

export default function ItemGrid({ items }) {
  const [expandedId, setExpandedId] = useState(null);
  const scrollRef = useRef(0);

  return expandedId ? (
    <ViewTransition enter="slide-in" name={`item-${expandedId}`}>
      <ItemDetail
        item={items.find(i => i.id === expandedId)}
        onClose={() => {
          startTransition(() => {
            setExpandedId(null);
            setTimeout(() => window.scrollTo({ behavior: 'smooth', top: scrollRef.current }), 100);
          });
        }}
      />
    </ViewTransition>
  ) : (
    <div className="grid grid-cols-3 gap-4">
      {items.map(item => (
        <ViewTransition key={item.id} name={`item-${item.id}`}>
          <ItemCard
            item={item}
            onSelect={() => {
              scrollRef.current = window.scrollY;
              startTransition(() => setExpandedId(item.id));
            }}
          />
        </ViewTransition>
      ))}
    </div>
  );
}

Cross-Fade Without Remount

Omit key to trigger update (cross-fade) instead of exit + enter. Avoids Suspense remount:

<ViewTransition><TabPanel tab={activeTab} /></ViewTransition>

Isolate Elements from Parent Animations

Persistent elements get captured in page's transition snapshot. Fix with viewTransitionName:

<nav style={{ viewTransitionName: "persistent-nav" }}>{/* ... */}</nav>

::view-transition-group(persistent-nav) { animation: none; z-index: 100; }

Same for floating elements (popovers, tooltips). Global fix: ::view-transition-group(*) { z-index: 100; }

Shared Controls Between Skeleton and Content

Give matching controls the same viewTransitionName. Don't put manual viewTransitionName on root DOM node inside <ViewTransition>.

Reusable Animated Collapse

function AnimatedCollapse({ open, children }) {
  if (!open) return null;
  return <ViewTransition enter="expand-in" exit="collapse-out">{children}</ViewTransition>;
}

Preserve State with Activity

<Activity mode={isVisible ? 'visible' : 'hidden'}>
  <ViewTransition enter="slide-in" exit="slide-out"><Sidebar /></ViewTransition>
</Activity>

Exclude Elements with useOptimistic

useOptimistic values update before snapshot, excluding them from animation. Use for controls; use committed state for animated content.

---

View Transition Events

Imperative control via onEnter, onExit, onUpdate, onShare. Always return cleanup. onShare takes precedence.

<ViewTransition
  onEnter={(instance, types) => {
    const anim = instance.new.animate(
      [{ transform: 'scale(0.8)', opacity: 0 }, { transform: 'scale(1)', opacity: 1 }],
      { duration: 300, easing: 'ease-out' }
    );
    return () => anim.cancel();
  }}
>
  <Component />
</ViewTransition>

instance: .old, .new, .group, .imagePair, .name

---

Animation Timing

Interaction	Duration
Direct toggle	100–200ms
Route transition	150–250ms
Suspense reveal	200–400ms
Shared element morph	300–500ms

---

Troubleshooting

VT not activating: Ensure VT comes before any DOM node. Ensure startTransition.

"Two VTs with same name": Names must be globally unique. Use IDs.

router.back() and browser back/forward skip animation: Use router.push() with an explicit URL instead.

Only updates animate: Without <Suspense>, React treats swaps as updates. Conditionally render the VT itself, or wrap in <Suspense>.

Layout VT prevents page VTs from animating: Nested VTs never fire enter/exit inside a parent VT. If your layout has a VT wrapping {children}, page-level enter/exit will silently not work. Remove the layout VT.

TS error "Property 'default' is missing": Type-keyed objects require a default key.

Backdrop-blur flickers: ::view-transition-old(name) { display: none } + ::view-transition-new(name) { animation: none }.

border-radius lost: Apply border-radius directly to captured element.

Batching: Multiple updates during animation are batched (A→B→C→D becomes B→D).

---

CSS Animation Recipes

Ready-to-use CSS for <ViewTransition> props. Copy into global stylesheet.

Timing Variables

:root {
  --duration-exit: 150ms;
  --duration-enter: 210ms;
  --duration-move: 400ms;
}

Shared Keyframes

@keyframes fade {
  from { filter: blur(3px); opacity: 0; }
  to { filter: blur(0); opacity: 1; }
}

@keyframes slide {
  from { translate: var(--slide-offset); }
  to { translate: 0; }
}

@keyframes slide-y {
  from { transform: translateY(var(--slide-y-offset, 10px)); }
  to { transform: translateY(0); }
}

Fade

::view-transition-old(.fade-out) {
  animation: var(--duration-exit) ease-in fade reverse;
}
::view-transition-new(.fade-in) {
  animation: var(--duration-enter) ease-out var(--duration-exit) both fade;
}

Slide (Vertical)

::view-transition-old(.slide-down) {
  animation:
    var(--duration-exit) ease-out both fade reverse,
    var(--duration-exit) ease-out both slide-y reverse;
}
::view-transition-new(.slide-up) {
  animation:
    var(--duration-enter) ease-in var(--duration-exit) both fade,
    var(--duration-move) ease-in both slide-y;
}

Directional Navigation

Single-Class Approach

::view-transition-old(.nav-forward) {
  --slide-offset: -60px;
  animation:
    var(--duration-exit) ease-in both fade reverse,
    var(--duration-move) ease-in-out both slide reverse;
}
::view-transition-new(.nav-forward) {
  --slide-offset: 60px;
  animation:
    var(--duration-enter) ease-out var(--duration-exit) both fade,
    var(--duration-move) ease-in-out both slide;
}

::view-transition-old(.nav-back) {
  --slide-offset: 60px;
  animation:
    var(--duration-exit) ease-in both fade reverse,
    var(--duration-move) ease-in-out both slide reverse;
}
::view-transition-new(.nav-back) {
  --slide-offset: -60px;
  animation:
    var(--duration-enter) ease-out var(--duration-exit) both fade,
    var(--duration-move) ease-in-out both slide;
}

Separate Enter/Exit Classes

::view-transition-new(.slide-from-right) {
  --slide-offset: 60px;
  animation:
    var(--duration-enter) ease-out var(--duration-exit) both fade,
    var(--duration-move) ease-in-out both slide;
}
::view-transition-old(.slide-to-left) {
  --slide-offset: -60px;
  animation:
    var(--duration-exit) ease-in both fade reverse,
    var(--duration-move) ease-in-out both slide reverse;
}

::view-transition-new(.slide-from-left) {
  --slide-offset: -60px;
  animation:
    var(--duration-enter) ease-out var(--duration-exit) both fade,
    var(--duration-move) ease-in-out both slide;
}
::view-transition-old(.slide-to-right) {
  --slide-offset: 60px;
  animation:
    var(--duration-exit) ease-in both fade reverse,
    var(--duration-move) ease-in-out both slide reverse;
}

Shared Element Morph

::view-transition-group(.morph) {
  animation-duration: var(--duration-move);
}
::view-transition-image-pair(.morph) {
  animation-name: via-blur;
}
@keyframes via-blur {
  30% { filter: blur(3px); }
}

Note: Shared element transitions take raster snapshots. For text with significant size differences (e.g., <h3> → <h1>), the old snapshot gets scaled up, producing a visible ghost artifact. Use text-morph for text shared elements.

Text Morph

Avoids raster scaling artifacts on text by hiding the old snapshot and showing the new text at full resolution:

::view-transition-group(.text-morph) {
  animation-duration: var(--duration-move);
}
::view-transition-old(.text-morph) {
  display: none;
}
::view-transition-new(.text-morph) {
  animation: none;
  object-fit: none;
  object-position: left top;
}

Scale

::view-transition-old(.scale-out) {
  animation: var(--duration-exit) ease-in scale-down;
}
::view-transition-new(.scale-in) {
  animation: var(--duration-enter) ease-out var(--duration-exit) both scale-up;
}
@keyframes scale-down {
  from { transform: scale(1); opacity: 1; }
  to { transform: scale(0.85); opacity: 0; }
}
@keyframes scale-up {
  from { transform: scale(0.85); opacity: 0; }
  to { transform: scale(1); opacity: 1; }
}

Persistent Element Isolation

::view-transition-group(persistent-nav) {
  animation: none;
  z-index: 100;
}

Backdrop-Blur Workaround

::view-transition-old(persistent-nav) { display: none; }
::view-transition-new(persistent-nav) { animation: none; }

Reduced Motion

@media (prefers-reduced-motion: reduce) {
  ::view-transition-old(*),
  ::view-transition-new(*),
  ::view-transition-group(*) {
    animation-duration: 0s !important;
    animation-delay: 0s !important;
  }
}

---

View Transitions in Next.js

Setup

// next.config.js
experimental: { viewTransition: true }

Wraps every <Link> navigation in document.startViewTransition. Use default="none" to prevent competing animations. Do not install react@canary — the App Router already bundles it.

Next.js Implementation Additions

After Step 2: Enable the experimental flag.

Step 4: Use transitionTypes on <Link> (if available — see availability note below):

<Link href="/photo/1" transitionTypes={["nav-forward"]}>View</Link>
<Link href="/" transitionTypes={["nav-back"]}>Back</Link>

After Step 6: For same-route dynamic segments, use key + name + share pattern.

Layout-Level ViewTransition

Don't add a layout-level VT wrapping {children} if pages have their own VTs — nested VTs never fire enter/exit inside a parent VT, so page-level enter/exit will silently not work. Remove the layout VT entirely. A bare VT in layout works only if pages have no VTs of their own. Layouts persist across navigations — don't use type-keyed maps in layouts.

The transitionTypes Prop

Works in Server Components, no wrapper needed:

<Link href="/products/1" transitionTypes={['nav-forward']}>View</Link>

Availability: Requires experimental.viewTransition: true. Available in Next.js 15+ canary builds and Next.js 16+. If unavailable, use startTransition + addTransitionType + router.push(). To check: grep -r "transitionTypes" node_modules/next/dist/. Reserve manual startTransition for non-link interactions.

loading.tsx as Suspense Boundary

Next.js loading.tsx files are implicit <Suspense> boundaries. Wrap the skeleton in <ViewTransition exit="..."> in loading.tsx, and the content in <ViewTransition enter="..." default="none"> in the page. This is the Next.js-idiomatic equivalent of explicit <Suspense fallback={...}>. Same rules apply: use simple string props (not type maps) since Suspense reveals fire without transition types.

Server-Side Filtering with router.replace

For search/sort/filter that re-renders on the server (via URL params), use startTransition + router.replace. VTs activate because the update is inside startTransition. List items wrapped in <ViewTransition key={item.id}> animate reorder. This is the server-component alternative to the client-side useDeferredValue pattern.

Two-Layer Pattern (Directional + Suspense)

Directional slides + Suspense reveals coexist because they fire at different moments. Place the directional VT in the page component (not layout):

<ViewTransition
  enter={{ "nav-forward": "slide-from-right", default: "none" }}
  exit={{ "nav-forward": "slide-to-left", default: "none" }}
  default="none"
>
  <div>
    <Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
      <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
    </Suspense>
  </div>
</ViewTransition>

Shared Elements Across Routes

// List page
<Link href={`/products/${product.id}`} transitionTypes={['nav-forward']}>
  <ViewTransition name={`product-${product.id}`}>
    <Image src={product.image} alt={product.name} width={400} height={300} />
  </ViewTransition>
</Link>

// Detail page — same name
<ViewTransition name={`product-${product.id}`}>
  <Image src={product.image} alt={product.name} width={800} height={600} />
</ViewTransition>

Same-Route Dynamic Segment Transitions

Page stays mounted on dynamic segment change — enter/exit never fire. Use key + name + share:

<Suspense fallback={<Skeleton />}>
  <ViewTransition key={slug} name={`collection-${slug}`} share="auto" default="none">
    <Content slug={slug} />
  </ViewTransition>
</Suspense>

Server Components

• <ViewTransition> works in Server and Client Components
• <Link transitionTypes> works in Server Components
• addTransitionType and programmatic nav require Client Components