AGENTS.md

1<!-- forgecat:@forgecat/vercel-labs_agent-skills_react-view-transitions:react-view-transitions-agents:start -->
2# React View Transitions
3 
4**Version 1.0.0**
5Vercel Engineering
6March 2026
7 
8> **Note:**
9> This document is mainly for agents and LLMs to follow when implementing
10> view transitions in React applications. Humans may also find it useful,
11> but guidance here is optimized for automation and consistency by
12> AI-assisted workflows.
13 
14---
15 
16## Abstract
17 
18Guide 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.
19 
20---
21 
22## Table of Contents
23 
241. [Core Reference](#when-to-animate)
25   - [When to Animate](#when-to-animate)
26   - [Availability](#availability)
27   - [Core Concepts](#core-concepts)
28   - [Styling with View Transition Classes](#styling-with-view-transition-classes)
29   - [Transition Types](#transition-types)
30   - [Shared Element Transitions](#shared-element-transitions)
31   - [Common Patterns](#common-patterns)
32   - [How Multiple VTs Interact](#how-multiple-vts-interact)
33   - [Next.js Integration](#nextjs-integration)
34   - [Accessibility](#accessibility)
352. [Implementation Workflow](#implementation-workflow)
36   - [Step 1: Audit the App](#step-1-audit-the-app)
37   - [Step 2: Add CSS Recipes](#step-2-add-css-recipes)
38   - [Step 3: Isolate Persistent Elements](#step-3-isolate-persistent-elements)
39   - [Step 4: Add Directional Page Transitions](#step-4-add-directional-page-transitions)
40   - [Step 5: Add Suspense Reveals](#step-5-add-suspense-reveals)
41   - [Step 6: Add Shared Element Transitions](#step-6-add-shared-element-transitions)
42   - [Step 7: Verify Each Navigation Path](#step-7-verify-each-navigation-path)
43   - [Common Mistakes](#common-mistakes)
443. [Patterns and Guidelines](#patterns-and-guidelines)
454. [CSS Animation Recipes](#css-animation-recipes)
465. [View Transitions in Next.js](#view-transitions-in-nextjs)
47 
48---
49 
50Animate 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.
51 
52## When to Animate
53 
54Every `<ViewTransition>` should communicate a spatial relationship or continuity. If you can't articulate what it communicates, don't add it.
55 
56Implement **all** applicable patterns from this list, in this order:
57 
58| Priority | Pattern | What it communicates |
59|----------|---------|---------------------|
60| 1 | **Shared element** (`name`) | "Same thing — going deeper" |
61| 2 | **Suspense reveal** | "Data loaded" |
62| 3 | **List identity** (per-item `key`) | "Same items, new arrangement" |
63| 4 | **State change** (`enter`/`exit`) | "Something appeared/disappeared" |
64| 5 | **Route change** (layout-level) | "Going to a new place" |
65 
66This 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.
67 
68### Choosing Animation Style
69 
70| Context | Animation | Why |
71|---------|-----------|-----|
72| Hierarchical navigation (list → detail) | Type-keyed `nav-forward` / `nav-back` | Communicates spatial depth |
73| Lateral navigation (tab-to-tab) | Bare `<ViewTransition>` (fade) or `default="none"` | No depth to communicate |
74| Suspense reveal | `enter`/`exit` string props | Content arriving |
75| Revalidation / background refresh | `default="none"` | Silent — no animation needed |
76 
77Reserve 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.
78 
79---
80 
81## Availability
82 
83- **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.
84- **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).
85- Browser support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful degradation.
86 
87---
88 
89## Core Concepts
90 
91### The `<ViewTransition>` Component
92 
93```jsx
94import { ViewTransition } from 'react';
95 
96<ViewTransition>
97  <Component />
98</ViewTransition>
99```
100 
101React auto-assigns a unique `view-transition-name` and calls `document.startViewTransition` behind the scenes. Never call `startViewTransition` yourself.
102 
103### Animation Triggers
104 
105| Trigger | When it fires |
106|---------|--------------|
107| **enter** | VT first inserted during a Transition |
108| **exit** | VT first removed during a Transition |
109| **update** | DOM mutations inside a VT. With nested VTs, mutation applies to the innermost one |
110| **share** | Named VT unmounts and another with same `name` mounts in same Transition |
111 
112Only `startTransition`, `useDeferredValue`, or `Suspense` activate VTs. Regular `setState` does not animate.
113 
114### Critical Placement Rule
115 
116VT only activates enter/exit if it appears **before any DOM nodes**:
117 
118```jsx
119// Works
120<ViewTransition enter="auto" exit="auto"><div>Content</div></ViewTransition>
121 
122// Broken — div wraps the VT
123<div><ViewTransition enter="auto" exit="auto"><div>Content</div></ViewTransition></div>
124```
125 
126---
127 
128## Styling with View Transition Classes
129 
130Values: `"auto"` (browser cross-fade), `"none"` (disabled), `"class-name"` (custom CSS), or `{ [type]: value }` for type-specific animations.
131 
132```jsx
133<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />
134```
135 
136If `default` is `"none"`, all triggers are off unless explicitly listed.
137 
138### CSS Pseudo-Elements
139 
140- `::view-transition-old(.class)` — outgoing snapshot
141- `::view-transition-new(.class)` — incoming snapshot
142- `::view-transition-group(.class)` — container
143- `::view-transition-image-pair(.class)` — old + new pair
144 
145---
146 
147## Transition Types
148 
149Tag 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:
150 
151```jsx
152startTransition(() => {
153  addTransitionType('nav-forward');
154  addTransitionType('select-item');
155  router.push('/detail/1');
156});
157```
158 
159Map types to CSS classes. Works on `enter`, `exit`, **and** `share`:
160 
161```jsx
162<ViewTransition
163  enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
164  exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
165  share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
166  default="none"
167>
168  <Page />
169</ViewTransition>
170```
171 
172`enter` and `exit` don't have to be symmetric. For example, fade in but slide out directionally:
173 
174```jsx
175<ViewTransition
176  enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
177  exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
178  default="none"
179>
180```
181 
182**TypeScript:** `ViewTransitionClassPerType` requires a `default` key.
183 
184### `router.back()` and Browser Back Button
185 
186`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.
187 
188### Types and Suspense
189 
190Types 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.
191 
192---
193 
194## Shared Element Transitions
195 
196Same `name` on two VTs — one unmounting, one mounting — creates a shared element morph:
197 
198```jsx
199<ViewTransition name="hero-image">
200  <img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
201</ViewTransition>
202 
203// Other view — same name
204<ViewTransition name="hero-image">
205  <img src="/full.jpg" />
206</ViewTransition>
207```
208 
209- 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.
210- `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.
211- Never use fade-out exit on pages with shared morphs — use directional slide.
212 
213---
214 
215## Common Patterns
216 
217### Enter/Exit
218 
219```jsx
220{show && (
221  <ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
222)}
223```
224 
225### List Reorder
226 
227```jsx
228{items.map(item => (
229  <ViewTransition key={item.id}><ItemCard item={item} /></ViewTransition>
230))}
231```
232 
233Trigger inside `startTransition`. Avoid wrapper `<div>`s between list and VT.
234 
235### Composing Shared Elements with List Identity
236 
237Shared 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:
238 
239```jsx
240{items.map(item => (
241  <ViewTransition key={item.id}>                                      {/* list identity */}
242    <Link href={`/items/${item.id}`}>
243      <ViewTransition name={`item-image-${item.id}`} share="morph">   {/* shared element */}
244        <Image src={item.image} />
245      </ViewTransition>
246      <p>{item.name}</p>
247    </Link>
248  </ViewTransition>
249))}
250```
251 
252The 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.
253 
254### Force Re-Enter with `key`
255 
256```jsx
257<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
258  <ResultsGrid />
259</ViewTransition>
260```
261 
262**Caution:** Wrapping `<Suspense>` with key remounts the boundary and refetches.
263 
264### Suspense Fallback to Content
265 
266Simple cross-fade:
267```jsx
268<ViewTransition>
269  <Suspense fallback={<Skeleton />}><Content /></Suspense>
270</ViewTransition>
271```
272 
273Directional reveal:
274```jsx
275<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
276  <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
277</Suspense>
278```
279 
280---
281 
282## How Multiple VTs Interact
283 
284Every VT matching the trigger fires simultaneously in a single `document.startViewTransition`. VTs in **different** transitions don't compete.
285 
286### Use `default="none"` Liberally
287 
288Without it, every VT fires the browser cross-fade on **every** transition. Always use `default="none"` and explicitly enable only desired triggers.
289 
290### Two Patterns Coexist
291 
292**Pattern A — Directional slides:** Type-keyed VT on each page, fires during navigation.
293**Pattern B — Suspense reveals:** Simple string props, fires when data loads (no type).
294 
295They 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.
296 
297### Nested VT Limitation
298 
299When 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](https://github.com/facebook/react/pull/36135) for an experimental opt-in fix.
300 
301---
302 
303## Next.js Integration
304 
305See the [View Transitions in Next.js](#view-transitions-in-nextjs) section below.
306 
307---
308 
309## Accessibility
310 
311Always add reduced motion CSS to your global stylesheet:
312 
313```css
314@media (prefers-reduced-motion: reduce) {
315  ::view-transition-old(*),
316  ::view-transition-new(*),
317  ::view-transition-group(*) {
318    animation-duration: 0s !important;
319    animation-delay: 0s !important;
320  }
321}
322```
323 
324---
325 
326# Implementation Workflow
327 
328**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.
329 
330## Step 1: Audit the App
331 
332Before writing any code, scan the codebase thoroughly. Search for:
333 
334- **Every `<Link>` and `router.push`** — open every file that contains one
335- **Every `<Suspense>` boundary** — check what its fallback renders
336- **Every page/route component** — each needs a VT placement decision
337- **Persistent elements** (headers, navbars, sidebars) — need `viewTransitionName` isolation
338- **Shared visual elements** on both source and target views
339- **Skeleton-to-content control pairs** — if a fallback renders a control that also exists in the real content, both need a matching `viewTransitionName`
340 
341Then classify every navigation and produce a navigation map:
342 
343```
344| Route           | Navigates to         | Direction    | VT pattern            |
345|-----------------|----------------------|--------------|-----------------------|
346| /               | /detail/[id]         | forward      | directional slide     |
347| /detail/[id]    | /                    | back         | directional slide     |
348| /detail/[id]    | /detail/[other]      | sequential   | directional slide (ordered prev/next) or key+share crossfade |
349| /tab/[a]        | /tab/[b]             | lateral      | key+share crossfade   |
350| (Suspense)      | (content loads)      | —            | slide-up reveal       |
351```
352 
353For 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`.
354 
355## Step 2: Add CSS Recipes
356 
357Copy 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.
358 
359## Step 3: Isolate Persistent Elements
360 
361```jsx
362<header style={{ viewTransitionName: "site-header" }}>...</header>
363```
364 
365```css
366::view-transition-group(site-header) {
367  animation: none;
368  z-index: 100;
369}
370```
371 
372For `backdrop-blur`/`backdrop-filter`, use the backdrop-blur workaround instead.
373 
374## Step 4: Add Directional Page Transitions
375 
376```jsx
377startTransition(() => {
378  addTransitionType('nav-forward');
379  router.push('/detail/1');
380});
381```
382 
383Wrap each **page component** (not layout) in a type-keyed VT:
384 
385```jsx
386<ViewTransition
387  enter={{ "nav-forward": "nav-forward", "nav-back": "nav-back", default: "none" }}
388  exit={{ "nav-forward": "nav-forward", "nav-back": "nav-back", default: "none" }}
389  default="none"
390>
391  <div>...page content...</div>
392</ViewTransition>
393```
394 
395Extract into a reusable component so every page doesn't repeat the type map:
396 
397```jsx
398export function DirectionalTransition({ children }: { children: React.ReactNode }) {
399  return (
400    <ViewTransition
401      enter={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
402      exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
403      default="none"
404    >
405      {children}
406    </ViewTransition>
407  );
408}
409```
410 
411**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).
412 
413## Step 5: Add Suspense Reveals
414 
415```jsx
416<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
417  <ViewTransition enter="slide-up" default="none"><AsyncContent /></ViewTransition>
418</Suspense>
419```
420 
421Use `default="none"` on content VT. Use simple string props (not type maps) — Suspense resolves have no type.
422 
423## Step 6: Add Shared Element Transitions
424 
425```jsx
426// Source view
427<ViewTransition name={`photo-${photo.id}`} share="morph" default="none">
428  <Image src={photo.src} ... />
429</ViewTransition>
430 
431// Target view — same name
432<ViewTransition name={`photo-${photo.id}`} share="morph">
433  <Image src={photo.src} ... />
434</ViewTransition>
435```
436 
437When list items contain shared elements, compose both patterns — two independent layers:
438 
439```jsx
440{items.map(item => (
441  <ViewTransition key={item.id}>                                        {/* list identity */}
442    <Link href={`/detail/${item.id}`}>
443      <ViewTransition name={`item-${item.id}`} share="morph" default="none">  {/* shared element */}
444        <Image src={item.image} ... />
445      </ViewTransition>
446    </Link>
447  </ViewTransition>
448))}
449```
450 
451The 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.
452 
453**Rules:** Names must be globally unique. Add `default="none"` on list-side shared elements.
454 
455## Step 7: Verify Each Navigation Path
456 
457Walk through every row in the navigation map from Step 1:
458 
459- Does the VT mount/unmount, or stay mounted (same-route)?
460- For named VTs: does a shared pair form? If not, does `enter`/`exit` provide a fallback?
461- Does `default="none"` block an animation you actually want?
462- Do persistent elements stay static?
463- Do Suspense reveals animate independently from directional navigations?
464 
465---
466 
467## Common Mistakes
468 
469- **Bare VT without `default="none"`** — fires cross-fade on every transition
470- **Directional VT in a layout** — layouts persist, enter/exit won't fire on route changes
471- **Fade-out exit with shared morphs** — conflicts with morph, use directional slide
472- **Writing custom animation CSS** — use the recipes
473- **Missing `default: "none"` in type-keyed objects** — TypeScript requires it, fallback is `"auto"`
474- **Type maps on Suspense reveals** — Suspense resolves have no type, use string props
475- **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.
476- **`update` trigger for same-route navigations** — nested VTs steal the mutation from the parent. Use `key` + `name` + `share` instead.
477- **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.
478- **`router.back()` for back navigation** — `router.back()` triggers synchronous `popstate`, incompatible with view transitions. Use `router.push()` with an explicit URL.
479 
480For Next.js-specific steps, see the Next.js section below.
481 
482---
483 
484# Patterns and Guidelines
485 
486## Searchable Grid with `useDeferredValue`
487 
488```tsx
489'use client';
490 
491import { useDeferredValue, useState, ViewTransition, Suspense } from 'react';
492 
493export default function SearchableGrid({ itemsPromise }) {
494  const [search, setSearch] = useState('');
495  const deferredSearch = useDeferredValue(search);
496 
497  return (
498    <>
499      <input value={search} onChange={(e) => setSearch(e.currentTarget.value)} />
500      <ViewTransition>
501        <Suspense fallback={<GridSkeleton />}>
502          <ItemGrid itemsPromise={itemsPromise} search={deferredSearch} />
503        </Suspense>
504      </ViewTransition>
505    </>
506  );
507}
508```
509 
510Per-item named VTs in deferred lists trigger cross-fades on every keystroke. Fix with `default="none"`.
511 
512## Card Expand/Collapse with `startTransition`
513 
514```tsx
515'use client';
516 
517import { useState, useRef, startTransition, ViewTransition } from 'react';
518 
519export default function ItemGrid({ items }) {
520  const [expandedId, setExpandedId] = useState(null);
521  const scrollRef = useRef(0);
522 
523  return expandedId ? (
524    <ViewTransition enter="slide-in" name={`item-${expandedId}`}>
525      <ItemDetail
526        item={items.find(i => i.id === expandedId)}
527        onClose={() => {
528          startTransition(() => {
529            setExpandedId(null);
530            setTimeout(() => window.scrollTo({ behavior: 'smooth', top: scrollRef.current }), 100);
531          });
532        }}
533      />
534    </ViewTransition>
535  ) : (
536    <div className="grid grid-cols-3 gap-4">
537      {items.map(item => (
538        <ViewTransition key={item.id} name={`item-${item.id}`}>
539          <ItemCard
540            item={item}
541            onSelect={() => {
542              scrollRef.current = window.scrollY;
543              startTransition(() => setExpandedId(item.id));
544            }}
545          />
546        </ViewTransition>
547      ))}
548    </div>
549  );
550}
551```
552 
553## Cross-Fade Without Remount
554 
555Omit `key` to trigger update (cross-fade) instead of exit + enter. Avoids Suspense remount:
556 
557```jsx
558<ViewTransition><TabPanel tab={activeTab} /></ViewTransition>
559```
560 
561## Isolate Elements from Parent Animations
562 
563Persistent elements get captured in page's transition snapshot. Fix with `viewTransitionName`:
564 
565```jsx
566<nav style={{ viewTransitionName: "persistent-nav" }}>{/* ... */}</nav>
567```
568 
569```css
570::view-transition-group(persistent-nav) { animation: none; z-index: 100; }
571```
572 
573Same for floating elements (popovers, tooltips). Global fix: `::view-transition-group(*) { z-index: 100; }`
574 
575## Shared Controls Between Skeleton and Content
576 
577Give matching controls the same `viewTransitionName`. Don't put manual `viewTransitionName` on root DOM node inside `<ViewTransition>`.
578 
579## Reusable Animated Collapse
580 
581```jsx
582function AnimatedCollapse({ open, children }) {
583  if (!open) return null;
584  return <ViewTransition enter="expand-in" exit="collapse-out">{children}</ViewTransition>;
585}
586```
587 
588## Preserve State with Activity
589 
590```jsx
591<Activity mode={isVisible ? 'visible' : 'hidden'}>
592  <ViewTransition enter="slide-in" exit="slide-out"><Sidebar /></ViewTransition>
593</Activity>
594```
595 
596## Exclude Elements with `useOptimistic`
597 
598`useOptimistic` values update before snapshot, excluding them from animation. Use for controls; use committed state for animated content.
599 
600---
601 
602## View Transition Events
603 
604Imperative control via `onEnter`, `onExit`, `onUpdate`, `onShare`. Always return cleanup. `onShare` takes precedence.
605 
606```jsx
607<ViewTransition
608  onEnter={(instance, types) => {
609    const anim = instance.new.animate(
610      [{ transform: 'scale(0.8)', opacity: 0 }, { transform: 'scale(1)', opacity: 1 }],
611      { duration: 300, easing: 'ease-out' }
612    );
613    return () => anim.cancel();
614  }}
615>
616  <Component />
617</ViewTransition>
618```
619 
620`instance`: `.old`, `.new`, `.group`, `.imagePair`, `.name`
621 
622---
623 
624## Animation Timing
625 
626| Interaction | Duration |
627|------------|----------|
628| Direct toggle | 100–200ms |
629| Route transition | 150–250ms |
630| Suspense reveal | 200–400ms |
631| Shared element morph | 300–500ms |
632 
633---
634 
635## Troubleshooting
636 
637**VT not activating:** Ensure VT comes before any DOM node. Ensure `startTransition`.
638 
639**"Two VTs with same name":** Names must be globally unique. Use IDs.
640 
641**`router.back()` and browser back/forward skip animation:** Use `router.push()` with an explicit URL instead.
642 
643**Only updates animate:** Without `<Suspense>`, React treats swaps as updates. Conditionally render the VT itself, or wrap in `<Suspense>`.
644 
645**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.
646 
647**TS error "Property 'default' is missing":** Type-keyed objects require a `default` key.
648 
649**Backdrop-blur flickers:** `::view-transition-old(name) { display: none }` + `::view-transition-new(name) { animation: none }`.
650 
651**`border-radius` lost:** Apply `border-radius` directly to captured element.
652 
653**Batching:** Multiple updates during animation are batched (A→B→C→D becomes B→D).
654 
655---
656 
657# CSS Animation Recipes
658 
659Ready-to-use CSS for `<ViewTransition>` props. Copy into global stylesheet.
660 
661## Timing Variables
662 
663```css
664:root {
665  --duration-exit: 150ms;
666  --duration-enter: 210ms;
667  --duration-move: 400ms;
668}
669```
670 
671### Shared Keyframes
672 
673```css
674@keyframes fade {
675  from { filter: blur(3px); opacity: 0; }
676  to { filter: blur(0); opacity: 1; }
677}
678 
679@keyframes slide {
680  from { translate: var(--slide-offset); }
681  to { translate: 0; }
682}
683 
684@keyframes slide-y {
685  from { transform: translateY(var(--slide-y-offset, 10px)); }
686  to { transform: translateY(0); }
687}
688```
689 
690## Fade
691 
692```css
693::view-transition-old(.fade-out) {
694  animation: var(--duration-exit) ease-in fade reverse;
695}
696::view-transition-new(.fade-in) {
697  animation: var(--duration-enter) ease-out var(--duration-exit) both fade;
698}
699```
700 
701## Slide (Vertical)
702 
703```css
704::view-transition-old(.slide-down) {
705  animation:
706    var(--duration-exit) ease-out both fade reverse,
707    var(--duration-exit) ease-out both slide-y reverse;
708}
709::view-transition-new(.slide-up) {
710  animation:
711    var(--duration-enter) ease-in var(--duration-exit) both fade,
712    var(--duration-move) ease-in both slide-y;
713}
714```
715 
716## Directional Navigation
717 
718### Single-Class Approach
719 
720```css
721::view-transition-old(.nav-forward) {
722  --slide-offset: -60px;
723  animation:
724    var(--duration-exit) ease-in both fade reverse,
725    var(--duration-move) ease-in-out both slide reverse;
726}
727::view-transition-new(.nav-forward) {
728  --slide-offset: 60px;
729  animation:
730    var(--duration-enter) ease-out var(--duration-exit) both fade,
731    var(--duration-move) ease-in-out both slide;
732}
733 
734::view-transition-old(.nav-back) {
735  --slide-offset: 60px;
736  animation:
737    var(--duration-exit) ease-in both fade reverse,
738    var(--duration-move) ease-in-out both slide reverse;
739}
740::view-transition-new(.nav-back) {
741  --slide-offset: -60px;
742  animation:
743    var(--duration-enter) ease-out var(--duration-exit) both fade,
744    var(--duration-move) ease-in-out both slide;
745}
746```
747 
748### Separate Enter/Exit Classes
749 
750```css
751::view-transition-new(.slide-from-right) {
752  --slide-offset: 60px;
753  animation:
754    var(--duration-enter) ease-out var(--duration-exit) both fade,
755    var(--duration-move) ease-in-out both slide;
756}
757::view-transition-old(.slide-to-left) {
758  --slide-offset: -60px;
759  animation:
760    var(--duration-exit) ease-in both fade reverse,
761    var(--duration-move) ease-in-out both slide reverse;
762}
763 
764::view-transition-new(.slide-from-left) {
765  --slide-offset: -60px;
766  animation:
767    var(--duration-enter) ease-out var(--duration-exit) both fade,
768    var(--duration-move) ease-in-out both slide;
769}
770::view-transition-old(.slide-to-right) {
771  --slide-offset: 60px;
772  animation:
773    var(--duration-exit) ease-in both fade reverse,
774    var(--duration-move) ease-in-out both slide reverse;
775}
776```
777 
778## Shared Element Morph
779 
780```css
781::view-transition-group(.morph) {
782  animation-duration: var(--duration-move);
783}
784::view-transition-image-pair(.morph) {
785  animation-name: via-blur;
786}
787@keyframes via-blur {
788  30% { filter: blur(3px); }
789}
790```
791 
792**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.
793 
794## Text Morph
795 
796Avoids raster scaling artifacts on text by hiding the old snapshot and showing the new text at full resolution:
797 
798```css
799::view-transition-group(.text-morph) {
800  animation-duration: var(--duration-move);
801}
802::view-transition-old(.text-morph) {
803  display: none;
804}
805::view-transition-new(.text-morph) {
806  animation: none;
807  object-fit: none;
808  object-position: left top;
809}
810```
811 
812## Scale
813 
814```css
815::view-transition-old(.scale-out) {
816  animation: var(--duration-exit) ease-in scale-down;
817}
818::view-transition-new(.scale-in) {
819  animation: var(--duration-enter) ease-out var(--duration-exit) both scale-up;
820}
821@keyframes scale-down {
822  from { transform: scale(1); opacity: 1; }
823  to { transform: scale(0.85); opacity: 0; }
824}
825@keyframes scale-up {
826  from { transform: scale(0.85); opacity: 0; }
827  to { transform: scale(1); opacity: 1; }
828}
829```
830 
831## Persistent Element Isolation
832 
833```css
834::view-transition-group(persistent-nav) {
835  animation: none;
836  z-index: 100;
837}
838```
839 
840### Backdrop-Blur Workaround
841 
842```css
843::view-transition-old(persistent-nav) { display: none; }
844::view-transition-new(persistent-nav) { animation: none; }
845```
846 
847## Reduced Motion
848 
849```css
850@media (prefers-reduced-motion: reduce) {
851  ::view-transition-old(*),
852  ::view-transition-new(*),
853  ::view-transition-group(*) {
854    animation-duration: 0s !important;
855    animation-delay: 0s !important;
856  }
857}
858```
859 
860---
861 
862# View Transitions in Next.js
863 
864## Setup
865 
866```js
867// next.config.js
868experimental: { viewTransition: true }
869```
870 
871Wraps every `<Link>` navigation in `document.startViewTransition`. Use `default="none"` to prevent competing animations. Do **not** install `react@canary` — the App Router already bundles it.
872 
873## Next.js Implementation Additions
874 
875**After Step 2:** Enable the experimental flag.
876 
877**Step 4:** Use `transitionTypes` on `<Link>` (if available — see availability note below):
878```tsx
879<Link href="/photo/1" transitionTypes={["nav-forward"]}>View</Link>
880<Link href="/" transitionTypes={["nav-back"]}>Back</Link>
881```
882 
883**After Step 6:** For same-route dynamic segments, use `key` + `name` + `share` pattern.
884 
885## Layout-Level ViewTransition
886 
887Don'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.
888 
889## The `transitionTypes` Prop
890 
891Works in Server Components, no wrapper needed:
892```tsx
893<Link href="/products/1" transitionTypes={['nav-forward']}>View</Link>
894```
895 
896**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.
897 
898## `loading.tsx` as Suspense Boundary
899 
900Next.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.
901 
902## Server-Side Filtering with `router.replace`
903 
904For 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.
905 
906## Two-Layer Pattern (Directional + Suspense)
907 
908Directional slides + Suspense reveals coexist because they fire at different moments. Place the directional VT in the **page component** (not layout):
909 
910```tsx
911<ViewTransition
912  enter={{ "nav-forward": "slide-from-right", default: "none" }}
913  exit={{ "nav-forward": "slide-to-left", default: "none" }}
914  default="none"
915>
916  <div>
917    <Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
918      <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
919    </Suspense>
920  </div>
921</ViewTransition>
922```
923 
924## Shared Elements Across Routes
925 
926```tsx
927// List page
928<Link href={`/products/${product.id}`} transitionTypes={['nav-forward']}>
929  <ViewTransition name={`product-${product.id}`}>
930    <Image src={product.image} alt={product.name} width={400} height={300} />
931  </ViewTransition>
932</Link>
933 
934// Detail page — same name
935<ViewTransition name={`product-${product.id}`}>
936  <Image src={product.image} alt={product.name} width={800} height={600} />
937</ViewTransition>
938```
939 
940## Same-Route Dynamic Segment Transitions
941 
942Page stays mounted on dynamic segment change — enter/exit never fire. Use `key` + `name` + `share`:
943 
944```tsx
945<Suspense fallback={<Skeleton />}>
946  <ViewTransition key={slug} name={`collection-${slug}`} share="auto" default="none">
947    <Content slug={slug} />
948  </ViewTransition>
949</Suspense>
950```
951 
952## Server Components
953 
954- `<ViewTransition>` works in Server and Client Components
955- `<Link transitionTypes>` works in Server Components
956- `addTransitionType` and programmatic nav require Client Components
957<!-- forgecat:@forgecat/vercel-labs_agent-skills_react-view-transitions:react-view-transitions-agents:end -->
958