{"page":{"pageid":372,"slug":"skill-vercel-react-view-transitions","title":"react-view-transitions skill (vercel-labs/agent-skills)","content":"**What it does.** Guide for implementing smooth, native-feeling animations using React's View Transition API (`` component, `addTransitionType`, and CSS view transition pseudo-elements). Use this skill whenever the user wants to add page transitions, animate route changes, create shared element animations, animate enter/exit of components, animate list reorder, implement directional (forward/back) navigation animations, or integrate view transitions in Next.js. Also use when the user mentions view transitions, `startViewTransition`, `ViewTransition`, transition types, or asks about animating between UI states in React without third-party animation libraries. Part of [[skills-vercel-agent-skills]] (vercel-labs/agent-skills).\n\n| | |\n| --- | --- |\n| Upstream | [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) |\n| Skill file | [skills/react-view-transitions/SKILL.md](https://github.com/vercel-labs/agent-skills/blob/HEAD/skills/react-view-transitions/SKILL.md) |\n| License | MIT (stated in the README; no LICENSE file) |\n| Author | Vercel Labs |\n| Fetched | 2026-09-10 |\n\n## Install\n\n- `npx skills add vercel-labs/agent-skills --skill react-view-transitions`, or copy the skill folder into `~/.claude/skills/react-view-transitions/`.\n- Raw file: `curl -sL https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-view-transitions/SKILL.md`\n\n## SKILL.md (verbatim)\n\n```yaml\nname: vercel-react-view-transitions\ndescription: Guide for implementing smooth, native-feeling animations using React's View Transition API (`` component, `addTransitionType`, and CSS view transition pseudo-elements). Use this skill whenever the user wants to add page transitions, animate route changes, create shared element animations, animate enter/exit of components, animate list reorder, implement directional (forward/back) navigation animations, or integrate view transitions in Next.js. Also use when the user mentions view transitions, `startViewTransition`, `ViewTransition`, transition types, or asks about animating between UI states in React without third-party animation libraries.\nlicense: MIT\nmetadata:\n author: vercel\n version: \"1.0.0\"\n```\n\n# React View Transitions\n\nAnimate between UI states using the browser's native `document.startViewTransition`. Declare *what* with ``, trigger *when* with `startTransition` / `useDeferredValue` / `Suspense`, control *how* with CSS classes. Unsupported browsers skip animations gracefully.\n\n## When to Animate\n\nEvery `` should communicate a spatial relationship or continuity. If you can't articulate what it communicates, don't add it.\n\nImplement **all** applicable patterns from this list, in this order:\n\n| Priority | Pattern | What it communicates |\n|----------|---------|---------------------|\n| 1 | **Shared element** (`name`) | \"Same thing — going deeper\" |\n| 2 | **Suspense reveal** | \"Data loaded\" |\n| 3 | **List identity** (per-item `key`) | \"Same items, new arrangement\" |\n| 4 | **State change** (`enter`/`exit`) | \"Something appeared/disappeared\" |\n| 5 | **Route change** (page-level) | \"Going to a new place\" |\n\nThis 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.\n\n### Choosing Animation Style\n\n| Context | Animation | Why |\n|---------|-----------|-----|\n| Hierarchical navigation (list → detail) | Type-keyed `nav-forward` / `nav-back` | Communicates spatial depth |\n| Lateral navigation (tab-to-tab) | Bare `` (fade) or `default=\"none\"` | No depth to communicate |\n| Suspense reveal | `enter`/`exit` string props | Content arriving |\n| Revalidation / background refresh | `default=\"none\"` | Silent — no animation needed |\n\nReserve 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.\n\n---\n\n## Availability\n\n- **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.\n- **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React).\n- Browser support: Chromium 125+ (React needs the v2 object form of `startViewTransition`), Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.\n\n---\n\n## Implementation Workflow\n\nWhen adding view transitions to an existing app, **follow [references/implementation.md](references/implementation.md) step by step.** Start with the audit — do not skip it. Use [references/css-recipes.md](references/css-recipes.md) for the applicable CSS and adapt it to the app.\n\n---\n\n## Core Concepts\n\n### The `` Component\n\n```jsx\nimport { ViewTransition } from 'react';\n\n\n \n\n```\n\nReact auto-assigns a unique `view-transition-name` and calls `document.startViewTransition` behind the scenes. Never call `startViewTransition` yourself.\n\n### Animation Triggers\n\n| Trigger | When it fires |\n|---------|--------------|\n| **enter** | `` first inserted during a Transition |\n| **exit** | `` first removed during a Transition |\n| **update** | DOM mutations inside a ``, or the boundary itself changing size/position due to an immediate sibling. With nested VTs, mutation applies to the innermost one |\n| **share** | Named VT unmounts and another with same `name` mounts in the same Transition |\n\nOnly `startTransition`, `useDeferredValue`, or `Suspense` activate VTs. Regular `setState` does not animate.\n\n### Critical Placement Rule\n\n`` only activates enter/exit if it appears **before any DOM nodes**:\n\n```jsx\n// Works\n\n
Content
\n\n\n// Broken — div wraps the VT, suppressing enter/exit\n
\n \n
Content
\n \n
\n```\n\n---\n\n## Styling with View Transition Classes\n\n### Props\n\nValues: `\"auto\"` (browser cross-fade), `\"none\"` (disabled), `\"class-name\"` (custom CSS), or `{ [type]: value }` for type-specific animations.\n\n```jsx\n\n```\n\nIf `default` is `\"none\"`, all triggers are off unless explicitly listed.\n\n### CSS Pseudo-Elements\n\n- `::view-transition-old(.class)` — outgoing snapshot\n- `::view-transition-new(.class)` — incoming snapshot\n- `::view-transition-group(.class)` — container\n- `::view-transition-image-pair(.class)` — old + new pair\n\nSee [references/css-recipes.md](references/css-recipes.md) for ready-to-use animation recipes.\n\n---\n\n## Transition Types\n\nTag transitions with `addTransitionType` so VTs can pick different animations based on context. Call it multiple times to stack types — different VTs in the tree react to different types:\n\n```jsx\nstartTransition(() => {\n addTransitionType('nav-forward');\n addTransitionType('select-item');\n router.push('/detail/1');\n});\n```\n\nPass an object to map types to CSS classes. Works on `enter`, `exit`, **and** `share`:\n\n```jsx\n\n \n\n```\n\n`enter` and `exit` don't have to be symmetric. For example, fade in but slide out directionally:\n\n```jsx\n\n```\n\n**TypeScript:** `ViewTransitionClassPerType` requires a `default` key in the object.\n\nFor apps with multiple pages, extract the type-keyed VT into a reusable wrapper:\n\n```jsx\nexport function DirectionalTransition({ children }: { children: React.ReactNode }) {\n return (\n \n {children}\n \n );\n}\n```\n\n### `router.back()` and Browser Back Button\n\n`router.back()` and the browser's back/forward buttons carry **no transition types**, so type-keyed animations (directional slides) resolve to their `default` and don't play — untyped shared-element morphs still apply. For typed animations, use `router.push()` with an explicit URL.\n\n### Types and Suspense\n\nTypes 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.\n\n### Shared Element Readiness\n\nA shared element transition can pair elements only when both the old and new views are rendered in the same Transition. If incoming content suspends, only its fallback exists for that update; the resolved content appears in a later Suspense transition and can be animated separately.\n\n---\n\n## Shared Element Transitions\n\nSame `name` on two VTs — one unmounting, one mounting — creates a shared element morph:\n\n```jsx\n\n startTransition(() => onSelect())} />\n\n\n// On the other view — same name\n\n \n\n```\n\n- Only one VT with a given `name` can be mounted at a time — use unique names (`photo-${id}`). 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.\n- `share` takes precedence over `enter`/`exit`. Think through each navigation path: when no matching pair forms (e.g., the target page doesn't have the same name), `enter`/`exit` fires instead. Consider whether the element needs a fallback animation for those paths.\n- Two ways a wired-up morph silently never fires: (1) `default=\"none\"` with no explicit `share` prop — share resolves to none; (2) type-keyed `share` where the navigation never adds the type — a plain link click resolves the map's `default`. Every link that should morph must add the type (`transitionTypes` on `next/link`, or `addTransitionType`).\n- Never use a fade-out exit on pages with shared morphs — use a directional slide instead.\n\n---\n\n## Common Patterns\n\n### Enter/Exit\n\n```jsx\n{show && (\n \n)}\n```\n\n### List Reorder\n\n```jsx\n{items.map(item => (\n \n))}\n```\n\nTrigger inside `startTransition`. Avoid wrapper `
`s between list and VT.\n\n### Layout Displacement Morph\n\nOnly content inside an activated boundary animates position — everything else teleports to its new layout spot. Wrap the sibling content below a growing/shrinking list in a bare `` so it glides instead of jumping. See [Layout Displacement Morph](references/patterns.md#layout-displacement-morph).\n\n### Composing Shared Elements with List Identity\n\nShared elements and list identity are independent concerns — don't confuse one for the other. When a list item contains a shared element (e.g., an image that morphs into a detail view), use two nested `` boundaries:\n\n```jsx\n{items.map(item => (\n {/* list identity */}\n \n {/* shared element */}\n \n \n

{item.name}

\n \n \n))}\n```\n\nThe outer VT handles list reorder/enter animations. The inner VT handles the cross-route shared element morph. Missing either layer means that animation silently doesn't happen.\n\n### Force Re-Enter with `key`\n\n```jsx\n\n \n\n```\n\n**Caution:** If wrapping ``, changing `key` remounts the boundary and refetches.\n\n### Suspense Fallback to Content\n\nSimple cross-fade:\n```jsx\n\n }>\n\n```\n\nDirectional reveal:\n```jsx\n}>\n \n\n```\n\nFor more patterns, see [references/patterns.md](references/patterns.md).\n\n---\n\n## How Multiple VTs Interact\n\nEvery VT matching the trigger fires simultaneously in a single `document.startViewTransition`. VTs in **different** transitions (navigation vs later Suspense resolve) don't compete.\n\n### Use `default=\"none\"` Deliberately\n\nWithout it, every VT fires the browser cross-fade on **every** transition — Suspense resolves, `useDeferredValue` updates, background revalidations. Use `default=\"none\"` on named/shared elements and type-keyed page VTs.\n\nBut it also turns off `update` (layout/reflow morphs) and `share` (a named pair with no explicit `share` prop never morphs). Keyed list items and displaced siblings *want* update — leave them bare or set `update=\"auto\"`.\n\n### Two Patterns Coexist\n\n**Pattern A — Directional slides:** Type-keyed VT on each page, fires during navigation.\n**Pattern B — Suspense reveals:** Simple string props, fires when data loads (no type).\n\nThey 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.\n\n### Nested VT Limitation\n\nWhen a parent VT mounts/unmounts **as one unit** with nested VTs inside it, the nested ones do not fire their own enter/exit — only the outermost VT animates. (A child VT mounted inside a *persistent* parent VT fires enter/exit normally.) Per-item staggered animations during page navigation are not currently available in Next.js; see [troubleshooting](references/troubleshooting.md) for the upstream experimental status.\n\n---\n\n## Next.js Integration\n\nFor Next.js integration (`transitionTypes` on `next/link` and `useRouter`, App Router patterns, Server Components), see [references/nextjs.md](references/nextjs.md).\n\n---\n\n## Accessibility\n\nAlways add the reduced motion CSS from [references/css-recipes.md](references/css-recipes.md#reduced-motion) to your global stylesheet.\n\n---\n\n## Reference Files\n\n- **[references/implementation.md](references/implementation.md)** — Step-by-step implementation workflow.\n- **[references/patterns.md](references/patterns.md)** — Patterns, animation timing, and events API.\n- **[references/troubleshooting.md](references/troubleshooting.md)** — Symptom-driven debugging and runtime limitations.\n- **[references/css-recipes.md](references/css-recipes.md)** — Ready-to-use CSS animation recipes.\n- **[references/nextjs.md](references/nextjs.md)** — Next.js App Router patterns and Server Component details.\n\n## Full Compiled Document\n\nFor the complete guide with all reference files expanded: `AGENTS.md`\n\n## Other files in this skill\n\n- [AGENTS.md](https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-view-transitions/AGENTS.md)\n- [README.md](https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-view-transitions/README.md)\n- [metadata.json](https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-view-transitions/metadata.json)\n- [references/css-recipes.md](https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-view-transitions/references/css-recipes.md)\n- [references/implementation.md](https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-view-transitions/references/implementation.md)\n- [references/nextjs.md](https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-view-transitions/references/nextjs.md)\n- [references/patterns.md](https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-view-transitions/references/patterns.md)\n- [references/troubleshooting.md](https://raw.githubusercontent.com/vercel-labs/agent-skills/HEAD/skills/react-view-transitions/references/troubleshooting.md)\n\n## README.md (verbatim)\n\n# React View Transitions Skill\n\nAn agent skill for implementing smooth, native-feeling animations using React's View Transition API.\n\n## What This Skill Covers\n\n- **`` component** — animation triggers (enter, exit, update, share), placement rules, View Transition Classes\n- **`addTransitionType`** — tagging transitions for directional or context-specific animations\n- **Shared element transitions** — morphing elements across different views\n- **View Transition Events** — imperative JavaScript animations via the Web Animations API\n- **CSS pseudo-elements** — `::view-transition-old`, `::view-transition-new`, `::view-transition-group`\n- **Next.js integration** — `transitionTypes` on `next/link` and `useRouter`, App Router patterns\n- **Accessibility** — `prefers-reduced-motion` handling\n- **Ready-to-use CSS recipes** — fade, slide, scale, directional navigation\n\n## Skill Structure\n\n```\nreact-view-transitions/\n├── SKILL.md # Core skill (always loaded)\n├── AGENTS.md # Full compiled document (all references expanded)\n└── references/\n ├── implementation.md # Step-by-step implementation workflow\n ├── patterns.md # Real-world patterns and events API\n ├── troubleshooting.md # Symptom-driven debugging\n ├── nextjs.md # Next.js-specific patterns\n └── css-recipes.md # Copy-paste CSS animations\n```\n\n## Installation\n\nInstall via [skills.sh](https://skills.sh):\n\n```bash\nnpx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-view-transitions\n```\n\n## Resources\n\n- [React `` docs](https://react.dev/reference/react/ViewTransition)\n- [React `addTransitionType` docs](https://react.dev/reference/react/addTransitionType)\n- [Next.js View Transitions guide](https://nextjs.org/docs/app/guides/view-transitions)\n- [Next.js `` `transitionTypes`](https://nextjs.org/docs/app/api-reference/components/link#transitiontypes)\n- [Next.js App Router Playground (view transitions)](https://github.com/vercel/next-app-router-playground/tree/main/app/view-transitions) — Vercel's reference implementation\n\n## references/css-recipes.md (verbatim)\n\n# CSS Animation Recipes\n\nReady-to-use CSS for `` props. Copy into your global stylesheet.\n\nThis file contains the complete CSS recipe set for the patterns in this skill. Copy only what the app needs.\n\n---\n\n## Timing Variables\n\n```css\n:root {\n --duration-exit: 150ms;\n --duration-enter: 210ms;\n --duration-move: 400ms;\n}\n```\n\n### Shared Keyframes\n\n```css\n@keyframes fade {\n from { opacity: 0; }\n to { opacity: 1; }\n}\n\n@keyframes slide {\n from { translate: var(--slide-offset); }\n to { translate: 0; }\n}\n\n@keyframes slide-y {\n from { transform: translateY(var(--slide-y-offset, 10px)); }\n to { transform: translateY(0); }\n}\n```\n\n---\n\n## Fade\n\n```css\n::view-transition-old(.fade-out) {\n animation: var(--duration-exit) ease-in fade reverse;\n}\n::view-transition-new(.fade-in) {\n animation: var(--duration-enter) ease-out var(--duration-exit) both fade;\n}\n```\n\nUsage: ``\n\nKeep the shared fade keyframe opacity-only. If a specific morph needs softness, give that class its own blur keyframe so ordinary content reveals stay crisp.\n\n---\n\n## Slide (Vertical)\n\n```css\n::view-transition-old(.slide-down) {\n animation:\n var(--duration-exit) ease-out both fade reverse,\n var(--duration-exit) ease-out both slide-y reverse;\n}\n::view-transition-new(.slide-up) {\n animation:\n var(--duration-enter) ease-in var(--duration-exit) both fade,\n var(--duration-move) ease-in both slide-y;\n}\n```\n\nUsage:\n```jsx\n}>\n \n\n```\n\n---\n\n## Directional Navigation\n\n### Separate Enter/Exit Classes\n\n```css\n::view-transition-new(.slide-from-right) {\n --slide-offset: 60px;\n animation:\n var(--duration-enter) ease-out var(--duration-exit) both fade,\n var(--duration-move) ease-in-out both slide;\n}\n::view-transition-old(.slide-to-left) {\n --slide-offset: -60px;\n animation:\n var(--duration-exit) ease-in both fade reverse,\n var(--duration-move) ease-in-out both slide reverse;\n}\n\n::view-transition-new(.slide-from-left) {\n --slide-offset: -60px;\n animation:\n var(--duration-enter) ease-out var(--duration-exit) both fade,\n var(--duration-move) ease-in-out both slide;\n}\n::view-transition-old(.slide-to-right) {\n --slide-offset: 60px;\n animation:\n var(--duration-exit) ease-in both fade reverse,\n var(--duration-move) ease-in-out both slide reverse;\n}\n```\n\n### Single-Class Approach\n\n```css\n::view-transition-old(.nav-forward) {\n --slide-offset: -60px;\n animation:\n var(--duration-exit) ease-in both fade reverse,\n var(--duration-move) ease-in-out both slide reverse;\n}\n::view-transition-new(.nav-forward) {\n --slide-offset: 60px;\n animation:\n var(--duration-enter) ease-out var(--duration-exit) both fade,\n var(--duration-move) ease-in-out both slide;\n}\n\n::view-transition-old(.nav-back) {\n --slide-offset: 60px;\n animation:\n var(--duration-exit) ease-in both fade reverse,\n var(--duration-move) ease-in-out both slide reverse;\n}\n::view-transition-new(.nav-back) {\n --slide-offset: -60px;\n animation:\n var(--duration-enter) ease-out var(--duration-exit) both fade,\n var(--duration-move) ease-in-out both slide;\n}\n```\n\n---\n\n## Shared Element Morph\n\n```css\n::view-transition-group(.morph) {\n animation-duration: var(--duration-move);\n}\n\n::view-transition-image-pair(.morph) {\n animation-name: via-blur;\n}\n\n@keyframes via-blur {\n 30% { filter: blur(3px); }\n}\n```\n\nUsage: ``\n\n**Note:** Shared element transitions take raster snapshots. For text with significant size differences (e.g., `

` → `

`), the old snapshot gets scaled up, producing a visible ghost artifact. Use `text-morph` for text shared elements.\n\n## Text Morph\n\nAvoids raster scaling artifacts on text by hiding the old snapshot and showing the new text at full resolution:\n\n```css\n::view-transition-group(.text-morph) {\n animation-duration: var(--duration-move);\n}\n::view-transition-old(.text-morph) {\n display: none;\n}\n::view-transition-new(.text-morph) {\n animation: none;\n object-fit: none;\n object-position: left top;\n}\n```\n\nUsage: ``\n\n---\n\n## Scale\n\n```css\n::view-transition-old(.scale-out) {\n animation: var(--duration-exit) ease-in scale-down;\n}\n::view-transition-new(.scale-in) {\n animation: var(--duration-enter) ease-out var(--duration-exit) both scale-up;\n}\n\n@keyframes scale-down {\n from { transform: scale(1); opacity: 1; }\n to { transform: scale(0.85); opacity: 0; }\n}\n@keyframes scale-up {\n from { transform: scale(0.85); opacity: 0; }\n to { transform: scale(1); opacity: 1; }\n}\n```\n\nUsage: ``\n\n---\n\n## Interactivity During Transitions\n\nThe `::view-transition` overlay captures all pointer events. React shrinks it to zero when the root group doesn't animate, but in-flight animations still block clicks. To pass clicks/hover through even while animating:\n\n```css\n::view-transition {\n pointer-events: none;\n}\n```\n\nTrade-offs: clicks can hit live elements under still-moving snapshots, and it only helps **unnamed** content — named participants are skipped by hit-testing for the transition's duration, no CSS override ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)). Weigh that before naming interactive elements; portal named popovers (see [Isolate Elements from Parent Animations](patterns.md#isolate-elements-from-parent-animations)).\n\n---\n\n## No Root Cross-Fade (Live Root)\n\nThe root cross-fades on every transition, freezing unnamed content behind a stale snapshot — hover and active styles stop rendering until it settles. `::view-transition-new(root)` is a **live** capture, so disabling the root animation keeps unnamed regions rendering (and, with the `pointer-events` recipe above, interactive):\n\n```css\n::view-transition-old(root) {\n display: none;\n}\n::view-transition-new(root) {\n animation: none;\n}\n```\n\nNamed and classed groups still animate — they stack above root. Trade-off: unnamed content swaps instantly, so regions that should fade need their own VT. This also removes the main reason to hand-name static chrome; keep names only for elements that must stack above animating groups.\n\nPairs well with enter-only reveals: skip the fallback-exit VT entirely (`` around the content, nothing on the skeleton) — the skeleton snaps out live while the content fades in.\n\n---\n\n## Persistent Element Isolation\n\n```css\n::view-transition-group(persistent-nav) {\n animation: none;\n z-index: 100;\n}\n```\n\nLayer multiple pinned groups with z-index tiers — chrome at `100`, toasts/overlays that must beat everything at `200`.\n\n### Backdrop-Blur Workaround\n\nFor elements with `backdrop-filter`, hide the old snapshot to avoid flash:\n\n```css\n::view-transition-old(persistent-nav) {\n display: none;\n}\n::view-transition-new(persistent-nav) {\n animation: none;\n}\n```\n\n### Floating Element Isolation (popovers, menus, tooltips, control clusters)\n\nSame freeze as persistent chrome. A floating/interactive element left rendered while a background transition runs is otherwise captured in the `root` snapshot and flickers as it settles. Give it a real, unique `view-transition-name` (never `none` — that's the CSS default = no isolation) and:\n\n```css\n::view-transition-group(popover) {\n animation: none;\n z-index: 100;\n}\n::view-transition-old(popover),\n::view-transition-new(popover) {\n animation: none;\n}\n```\n\n### Sliding Indicator (tab underline / segmented pill)\n\nOne shared-name indicator morphs between positions. Slide the group; disable old/new so the solid bar slides instead of cross-fading:\n\n```css\n::view-transition-group(.tab-underline) {\n animation-duration: 220ms;\n animation-timing-function: cubic-bezier(0.5, 0, 0.2, 1);\n}\n::view-transition-old(.tab-underline),\n::view-transition-new(.tab-underline) {\n animation: none;\n height: 100%;\n}\n```\n\n---\n\n## Reduced Motion\n\n```css\n@media (prefers-reduced-motion: reduce) {\n ::view-transition-old(*),\n ::view-transition-new(*),\n ::view-transition-group(*) {\n animation-duration: 0s !important;\n animation-delay: 0s !important;\n }\n}\n```\n\n## references/implementation.md (verbatim)\n\n# Implementation Workflow\n\nFollow these steps in order when adding view transitions to an app. Each step builds on the previous one.\n\nUse the official [React `` reference](https://react.dev/reference/react/ViewTransition) and [Next.js guide](https://nextjs.org/docs/app/guides/view-transitions) for API behavior. This file focuses on audit order, integration decisions, and verification.\n\n## Step 1: Audit the App\n\nBefore writing any code, scan the codebase thoroughly. Search for:\n\n- **Every `` and `router.push`** — these are your navigation triggers. Open every file that contains one.\n- **Every `` boundary** — each one is a candidate for a reveal animation. Check what its fallback renders.\n- **Every page/route component** — list them all. Each page needs a VT placement decision.\n- **Persistent elements** — headers, navbars, sidebars, sticky controls that stay on screen across navigations. These need `viewTransitionName` isolation.\n- **Shared visual elements** — images, cards, or avatars that appear on both a source and target view (e.g., a thumbnail in a list and the same image on a detail page).\n- **Skeleton-to-content control pairs** — if a Suspense fallback renders a control (search input, tab bar) that also exists in the real content, both need a matching `viewTransitionName`.\n\nThen classify every navigation and produce a navigation map:\n\n```\n| Route | Navigates to | Direction | VT pattern |\n|-----------------|----------------------|--------------|-----------------------|\n| / | /detail/[id] | forward | directional slide |\n| /detail/[id] | / | back | directional slide |\n| /detail/[id] | /detail/[other] | sequential | directional slide (ordered prev/next) or key+share crossfade |\n| /tab/[a] | /tab/[b] | lateral | key+share crossfade |\n| (Suspense) | (content loads) | — | slide-up reveal |\n```\n\nFor each shared element (`name` prop), note every navigation where a pair forms and where it doesn't — this determines whether you need `enter`/`exit` as a fallback alongside `share`.\n\n## Step 2: Add CSS Recipes\n\nChoose the animation pattern from the audit and this skill's guidance, then copy only the applicable sections from [css-recipes.md](css-recipes.md). Always include reduced motion. Add live-root, persistent-element, backdrop, or floating-element rules only when the audit found those surfaces.\n\nCustomize timing after the structure works. Keep ordinary crossfades opacity-only; scope blur to a specific shared morph when it is intentional.\n\n## Step 3: Isolate Persistent Elements\n\nFor every persistent element identified in Step 1, add a `viewTransitionName` style to pull it out of the page content's transition snapshot:\n\n```jsx\n
...
\n```\n\nThen add the [Persistent Element Isolation](css-recipes.md#persistent-element-isolation) CSS (prevents the element from animating during page transitions). If the element uses `backdrop-blur` or `backdrop-filter`, use the [Backdrop-Blur Workaround](css-recipes.md#backdrop-blur-workaround) instead.\n\nIf a Suspense fallback mirrors a persistent control (e.g., a skeleton search input), give both the real control and the skeleton the same `viewTransitionName` so they morph in place.\n\n## Step 4: Add Directional Page Transitions\n\nFor hierarchical navigations identified in Step 1, tag the navigation direction using `addTransitionType` inside `startTransition`:\n\n```jsx\nstartTransition(() => {\n addTransitionType('nav-forward');\n router.push('/detail/1');\n});\n```\n\nThen wrap each **page component** (not layout) in a type-keyed ``:\n\n```jsx\n\n
...page content...
\n\n```\n\nThe `nav-forward` and `nav-back` CSS classes from [Directional Navigation](css-recipes.md#directional-navigation) produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `` wrapper with `enter=\"fade-in\"` / `exit=\"fade-out\"` works too.\n\nExtract this into a reusable component so every page doesn't repeat the verbose type map:\n\n```jsx\nexport function DirectionalTransition({ children }: { children: React.ReactNode }) {\n return (\n \n {children}\n \n );\n}\n```\n\nThis also becomes the single place to adjust if you add new transition types later.\n\n**Rules:**\n- Always pair `enter` with `exit` — without an exit animation, the old page disappears instantly while the new one animates in.\n- Always include `default: \"none\"` in type map objects and `default=\"none\"` on the component — otherwise it fires on every transition.\n- Place the directional `` in each page component, not in a layout. Layouts persist across navigations and never trigger enter/exit.\n- Only use directional slides for hierarchical navigation or ordered sequences (prev/next). Lateral/sibling navigation (tab-to-tab) should use a bare `` (cross-fade) or `default=\"none\"`.\n\n## Step 5: Add Suspense Reveals\n\nFor every `` boundary identified in Step 1, wrap the fallback and content in separate ``s:\n\n```jsx\n\n \n \n }\n>\n \n \n \n\n```\n\nThis example uses `slide-down` / `slide-up` for directional vertical motion. For a simpler reveal, a bare `` around the `` gives a cross-fade with zero configuration. Choose based on the spatial meaning described in the main skill.\n\n**Rules:**\n- Always use `default=\"none\"` on the content `` to prevent re-animation on revalidation or unrelated transitions.\n- Use simple string props (not type maps) on Suspense ``s — Suspense resolves fire as separate transitions with no type, so type-keyed props won't match.\n- A fallback/content `share` pair morphs between snapshots. Use it only when that interpolation is desired and does not distort layout or geometry.\n- If the same element appears in **both** the fallback and the content (a title, a heading), it flickers on reveal — an opacity dip. Render it **outside** the `` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](patterns.md#suspense-reveal-flicker).\n\n## Step 6: Add Shared Element Transitions\n\nFor every shared visual element identified in Step 1, add matching named `` wrappers on both the source and target views:\n\n```jsx\n// On the source view (e.g., list/grid page)\n\n \n\n\n// On the target view (e.g., detail page) — same name\n\n \n\n```\n\nThe `share=\"morph\"` class uses the [Shared Element Morph](css-recipes.md#shared-element-morph) recipe (controlled duration + motion blur). For a simpler cross-fade, use `share=\"auto\"` (browser default).\n\nWhen list items contain shared elements, compose both patterns with two nested `` layers — an outer keyed VT for list identity and an inner named VT for the cross-route pair. See [Composing Shared Elements with List Identity](../SKILL.md#composing-shared-elements-with-list-identity).\n\n**Rules:**\n- Names must be globally unique — use prefixes like `photo-${id}`.\n- Add `default=\"none\"` on list-side shared elements to prevent per-item cross-fades on filter/search updates.\n- The target must be **in the DOM at navigation time** for the pair to form. If it's behind a Suspense fallback (not rendered yet), no pair forms and it won't morph. It works when the target is present at the snapshot — render it above the data boundary, or have its data **cached/prefetched** so it resolves in time.\n\n## Step 7: Verify Each Navigation Path\n\nWalk through every row in the navigation map from Step 1 and confirm:\n\n- Does the VT mount/unmount on this navigation, or does it stay mounted (same-route)?\n- For named VTs: does a shared pair form? If not, does `enter`/`exit` provide a fallback?\n- Does `default=\"none\"` block an animation you actually want?\n- Do persistent elements stay static (not sliding with page content)?\n- Do Suspense reveals animate independently from directional navigations?\n\nIf any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](troubleshooting.md).\n\nFor Next.js-specific implementation steps (`transitionTypes` on ``, prefetch behavior, and same-route dynamic segments), see [nextjs.md](nextjs.md).\n\n## references/nextjs.md (verbatim)\n\n# View Transitions in Next.js\n\n## Setup\n\n`` works in the App Router with no configuration. The bundled React channel includes it, and Next.js navigations run in React Transitions. Do **not** add the old `experimental.viewTransition` flag or install `react@canary` into a Next.js app.\n\nRead the current [Next.js View Transitions guide](https://nextjs.org/docs/app/guides/view-transitions) and the matching guide under `node_modules/next/dist/docs/` before editing. The installed version is authoritative for flags and API signatures.\n\nBecause every link click is a transition, any VT with `default=\"auto\"` fires on **every** navigation — use `default=\"none\"` to prevent competing animations.\n\nFor unexpected or broken animation behavior, see [troubleshooting.md](troubleshooting.md).\n\n---\n\n## Next.js Implementation Additions\n\nWhen following [implementation.md](implementation.md), apply these additions:\n\n**Step 4:** Use `transitionTypes` on `` — see [The `transitionTypes` Prop](#the-transitiontypes-prop-on-nextlink). If the animation depends on dynamic destination content, also see [When Content Must Be Ready](#when-content-must-be-ready).\n\n**After Step 6:** For same-route dynamic segments (e.g., `/collection/[slug]`), use the `key` + `name` + `share` pattern — see [Same-Route Dynamic Segment Transitions](#same-route-dynamic-segment-transitions).\n\n---\n\n## Layout-Level ViewTransition\n\n**Do NOT add a layout-level VT wrapping `{children}` if pages have their own VTs.** A nested VT skips its own enter/exit only when it mounts or unmounts *as one unit* with a parent VT, which is exactly what a layout VT wrapping `{children}` causes — page-level enter/exit will silently not work. Remove the layout VT entirely. Nesting is otherwise fine and sometimes required: a child VT inside a *persistent* parent VT fires enter/exit normally, and two nested boundaries are the intended shape for [shared elements inside list items](../SKILL.md#composing-shared-elements-with-list-identity).\n\nA bare `` in layout works only if pages have **no** VTs of their own.\n\n**Layouts persist across navigations** — `enter`/`exit` only fire on initial mount, not on route changes. Don't use type-keyed maps in layouts. Because layouts persist, chrome hosted in one (nav, sidebar, player) keeps its state across navigations for free — no `Activity` needed. Reserve `Activity` for in-page show/hide (see [Composing with Activity](patterns.md#composing-with-activity)).\n\n---\n\n## The `transitionTypes` Prop on `next/link`\n\nNo wrapper component needed, works in Server Components:\n\n```tsx\n\n View Product\n\n```\n\nReplaces the manual pattern of `onNavigate` + `startTransition` + `addTransitionType` + `router.push()`. Reserve manual `startTransition` for non-link interactions (buttons, forms).\n\n**Availability:** `transitionTypes` shipped in **Next.js 16.2.0** (it is not gated on the `experimental.viewTransition` flag). If unavailable, use `startTransition` + `addTransitionType` + `router.push()` (see [Programmatic Navigation](#programmatic-navigation)). To check: `grep -r \"transitionTypes\" node_modules/next/dist/` — if no results, fall back to programmatic navigation.\n\n---\n\n## When Content Must Be Ready\n\nA page transition can animate whatever Next.js renders during navigation, including a loading fallback. A shared content-to-content morph only works when the incoming content is ready as the navigation commits; content that has not rendered yet cannot form the incoming half of the pair.\n\nWhen an animation depends on dynamic destination content, use Next.js prefetching and caching to make that content available ahead of time. `` automatically prefetches in production, but the default behavior for dynamic routes may only prefetch a shell or loading boundary. Set `prefetch={true}` to prefetch the full route, and cache the data needed to render the shared content.\n\n```tsx\n\n Next\n\n```\n\nWith Cache Components, put reusable route data in a cached scope such as `use cache` so prefetching can include it. If the destination remains behind an unresolved Suspense boundary, the route transition animates the fallback instead. The content resolves in a separate Suspense transition without the original `nav-forward` or `nav-back` type, so give that content its own reveal animation when needed.\n\nVerify directional transitions in a production build with a cold client cache. Development mode does not run automatic `` prefetching.\n\nSee the Next.js [View Transitions guide](https://nextjs.org/docs/app/guides/view-transitions) and [Prefetching guide](https://nextjs.org/docs/app/guides/prefetching).\n\n---\n\n## Programmatic Navigation\n\n```tsx\n'use client';\n\nimport { useRouter } from 'next/navigation';\n\nfunction DetailButton({ href }: { href: string }) {\n const router = useRouter();\n\n return (\n \n );\n}\n```\n\nThe `transitionTypes` option adds the types inside the router's navigation Transition. Use `startTransition` + `addTransitionType` for non-navigation state updates, or as a fallback on Next.js versions without the router option.\n\n---\n\n## Server-Side Filtering with `router.replace`\n\nFor search/sort/filter that re-renders on the server (via URL params), use `startTransition` + `router.replace`. VTs activate because the state update is inside `startTransition`:\n\n```tsx\n'use client';\n\nimport { useRouter } from 'next/navigation';\nimport { startTransition } from 'react';\n\nfunction SortControl() {\n const router = useRouter();\n\n function handleSort(sort: string) {\n startTransition(() => {\n router.replace(`?sort=${sort}`);\n });\n }\n\n return ;\n}\n```\n\nList items wrapped in `` will animate reorder. This is the server-component alternative to the client-side [Searchable Grid](patterns.md#searchable-grid-with-usedeferredvalue) pattern.\n\nFor immediate control feedback while the route commits, use `useOptimistic` for the button state but keep the animated list tied to the committed sort value. See [Exclude Elements with `useOptimistic`](patterns.md#exclude-elements-with-useoptimistic).\n\n---\n\n## Routing-Driven Tabs\n\nThe generalized sliding indicator ([Sliding Indicator](patterns.md#sliding-indicator-tabs)) driven by navigation instead of local state: tabs are ``s, `active` comes from the URL (a server prop), and `useOptimistic` slides the indicator instantly while the route commits. Key the mounted indicator to committed `active` so the bar lands where navigation actually settles.\n\n```tsx\n'use client';\nimport Link from 'next/link';\nimport { useOptimistic, useTransition, ViewTransition } from 'react';\n\nexport function Tabs({ tabs, active, indicatorName = 'tab-indicator' }) {\n const [optimisticActive, setOptimisticActive] = useOptimistic(active);\n const [, startTransition] = useTransition();\n return (\n \n );\n}\n```\n\n---\n\n## Two-Layer Pattern (Directional + Suspense)\n\nDirectional slides + Suspense reveals coexist because they fire at different moments. Place the directional VT in the **page component** (not layout):\n\n```tsx\n\n
\n }>\n \n \n
\n\n```\n\n---\n\n## `loading.tsx` as Suspense Boundary\n\nNext.js `loading.tsx` is an implicit `` boundary. Wrap the skeleton in `` in `loading.tsx`, and the content in `` in the page:\n\n```tsx\n// loading.tsx\n\n\n// page.tsx\n\n```\n\nSame rules as explicit ``: use simple string props (not type maps) since Suspense reveals fire without transition types.\n\n---\n\n## Shared Elements Across Routes\n\n```tsx\n// List page\n{products.map((product) => (\n \n \n {product.name}\n \n \n))}\n\n// Detail page — same name\n\n {product.name}\n\n```\n\nIf the pair's `share` is type-keyed (or classed via CSS that expects a type), every `` between the two views must carry the type via `transitionTypes` — a plain link click resolves the share map's `default`, and if that's `none` the morph silently never fires.\n\n---\n\n## Same-Route Dynamic Segment Transitions\n\nWhen navigating between dynamic segments of the same route (e.g., `/collection/[slug]`), the router swaps subtrees keyed by the segment value rather than doing a plain unmount/mount — enter/exit don't fire reliably. Use `key` + `name` + `share`:\n\n```tsx\n}>\n \n \n \n\n```\n\n- `key={slug}` forces unmount/remount on change\n- The stable `name` pairs the outgoing and incoming containers; `share=\"auto\"` creates the crossfade\n- VT inside `` (without keying Suspense) keeps old content visible during loading\n\n## Server Components\n\n- `` works in both Server and Client Components\n- `` works in Server Components — no `'use client'` needed\n- `router.push(..., { transitionTypes })`, `addTransitionType`, and `startTransition` require Client Components\n\n## references/patterns.md (verbatim)\n\n# Patterns and Guidelines\n\nUse the official [React `` reference](https://react.dev/reference/react/ViewTransition) for API mechanics. This file collects reusable implementation patterns and failure modes from production apps.\n\n## Searchable Grid with `useDeferredValue`\n\n`useDeferredValue` makes filter updates a transition, activating ``:\n\n```tsx\n'use client';\n\nimport { useDeferredValue, useState, ViewTransition, Suspense } from 'react';\n\nexport default function SearchableGrid({ itemsPromise }) {\n const [search, setSearch] = useState('');\n const deferredSearch = useDeferredValue(search);\n\n return (\n <>\n setSearch(e.currentTarget.value)} />\n \n }>\n \n \n \n \n );\n}\n```\n\nPer-item `` inside a deferred list triggers cross-fades on every keystroke. Fix with `default=\"none\"`:\n\n```tsx\n{filteredItems.map(item => (\n \n \n \n))}\n```\n\n## Card Expand/Collapse with `startTransition`\n\nToggle between grid and detail view with shared element morph:\n\n```tsx\n'use client';\n\nimport { useState, useRef, startTransition, ViewTransition } from 'react';\n\nexport default function ItemGrid({ items }) {\n const [expandedId, setExpandedId] = useState(null);\n const scrollRef = useRef(0);\n\n return expandedId ? (\n \n i.id === expandedId)}\n onClose={() => {\n startTransition(() => {\n setExpandedId(null);\n setTimeout(() => window.scrollTo({ behavior: 'smooth', top: scrollRef.current }), 100);\n });\n }}\n />\n \n ) : (\n
\n {items.map(item => (\n \n {\n scrollRef.current = window.scrollY;\n startTransition(() => setExpandedId(item.id));\n }}\n />\n \n ))}\n
\n );\n}\n```\n\n## Type-Safe Transition Helpers\n\nUse `as const` arrays and derived types to prevent ID clashes:\n\n```tsx\nconst transitionTypes = ['default', 'transition-to-detail', 'transition-to-list'] as const;\nconst animationTypes = ['auto', 'none', 'animate-slide-from-left', 'animate-slide-from-right'] as const;\n\ntype TransitionType = (typeof transitionTypes)[number];\ntype AnimationType = (typeof animationTypes)[number];\ntype TransitionMap = { default: AnimationType } & Partial, AnimationType>>;\n\nexport function HorizontalTransition({ children, enter, exit }: {\n children: React.ReactNode;\n enter: TransitionMap;\n exit: TransitionMap;\n}) {\n return {children};\n}\n```\n\n## Cross-Fade Without Remount\n\nOmit `key` to trigger an update (cross-fade) instead of exit + enter. Avoids Suspense remount/refetch:\n\n```jsx\n\n \n\n```\n\nUse `key` when content identity changes (state resets). Omit for cross-fades (tabs, panels, carousel).\n\n## Isolate Elements from Parent Animations\n\nPull an element out of the animated `root` snapshot by giving it its own `view-transition-name`. **`view-transition-name: none` is a no-op** — it's the CSS default, so the element stays in `root` (a common flicker bug). Use a real, unique name, then neutralize with `` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](css-recipes.md#persistent-element-isolation)).\n\n- **Persistent chrome** (nav, sidebar, player bar): `