git:20260526.54acd2a to git:20261022.752a38b

+ > This standalone guide is compiled from `SKILL.md` and its reference files

+ > for agents that consume a single `AGENTS.md` document. Edit the source

+ > files, not this compiled copy.

+ | 5 | **Route change** (page-level) | "Going to a new place" |

+ - Browser support: Chromium 125+ (React needs the v2 object form of `startViewTransition`), Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers.

+ ## Implementation Workflow

+

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

+

+ ---

+

+ | Trigger | When it fires |

+ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

+ | **enter** | `<ViewTransition>` first inserted during a Transition |

+ | **exit** | `<ViewTransition>` first removed during a Transition |

+ | **update** | DOM mutations inside a `<ViewTransition>`, or the boundary itself changing size/position due to an immediate sibling. With nested VTs, mutation applies to the innermost one |

+ | **share** | Named VT unmounts and another with same `name` mounts in the same Transition |

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

+ <ViewTransition enter="auto" exit="auto">

+ <div>Content</div>

+ </ViewTransition>

+ // Broken — div wraps the VT, suppressing enter/exit

+ <div>

+ <ViewTransition enter="auto" exit="auto">

+ <div>Content</div>

+ </ViewTransition>

+ </div>

+ ### Props

+

+ See [references/css-recipes.md](references/css-recipes.md) for ready-to-use animation recipes.

+

+ Tag 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:

+ Pass an object to map types to CSS classes. Works on `enter`, `exit`, **and** `share`:

+ **TypeScript:** `ViewTransitionClassPerType` requires a `default` key in the object.

+ For apps with multiple pages, extract the type-keyed VT into a reusable wrapper:

+

+ ```jsx

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

+ );

+ }

+ ```

+

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

+ ### Shared Element Readiness

+

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

+

+ // On the other view — same name

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

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

+ - 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`).

+ - Never use a fade-out exit on pages with shared morphs — use a directional slide instead.

+ ### Layout Displacement Morph

+

+ Only 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 `<ViewTransition>` so it glides instead of jumping. See [Layout Displacement Morph](references/patterns.md#layout-displacement-morph).

+

+ Shared 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 `<ViewTransition>` boundaries:

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

+ **Caution:** If wrapping `<Suspense>`, changing `key` remounts the boundary and refetches.

+ For more patterns, see [references/patterns.md](references/patterns.md).

+

+ Every VT matching the trigger fires simultaneously in a single `document.startViewTransition`. VTs in **different** transitions (navigation vs later Suspense resolve) don't compete.

+ ### Use `default="none"` Deliberately

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

+ But 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"`.

+

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

+ For Next.js integration (`transitionTypes` on `next/link` and `useRouter`, App Router patterns, Server Components), see [references/nextjs.md](references/nextjs.md).

+ Always add the reduced motion CSS from [references/css-recipes.md](references/css-recipes.md#reduced-motion) to your global stylesheet.

+ ---

+ ## Reference Files

+

+ - **[references/implementation.md](references/implementation.md)** — Step-by-step implementation workflow.

+ - **[references/patterns.md](references/patterns.md)** — Patterns, animation timing, and events API.

+ - **[references/troubleshooting.md](references/troubleshooting.md)** — Symptom-driven debugging and runtime limitations.

+ - **[references/css-recipes.md](references/css-recipes.md)** — Ready-to-use CSS animation recipes.

+ - **[references/nextjs.md](references/nextjs.md)** — Next.js App Router patterns and Server Component details.

+

+ Follow these steps in order when adding view transitions to an app. Each step builds on the previous one.

+ Use the official [React `<ViewTransition>` 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.

+

+ - **Every `<Link>` and `router.push`** — these are your navigation triggers. Open every file that contains one.

+ - **Every `<Suspense>` boundary** — each one is a candidate for a reveal animation. Check what its fallback renders.

+ - **Every page/route component** — list them all. Each page needs a VT placement decision.

+ - **Persistent elements** — headers, navbars, sidebars, sticky controls that stay on screen across navigations. These need `viewTransitionName` isolation.

+ - **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).

+ - **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`.

+ For 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`.

+ Choose the animation pattern from the audit and this skill's guidance, then copy only the applicable sections from [css-recipes.md](references/css-recipes.md). Always include reduced motion. Add live-root, persistent-element, backdrop, or floating-element rules only when the audit found those surfaces.

+ Customize timing after the structure works. Keep ordinary crossfades opacity-only; scope blur to a specific shared morph when it is intentional.

+

+ For every persistent element identified in Step 1, add a `viewTransitionName` style to pull it out of the page content's transition snapshot:

+

+ Then add the [Persistent Element Isolation](references/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](references/css-recipes.md#backdrop-blur-workaround) instead.

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

+ For hierarchical navigations identified in Step 1, tag the navigation direction using `addTransitionType` inside `startTransition`:

+

+ Then wrap each **page component** (not layout) in a type-keyed `<ViewTransition>`:

+ The `nav-forward` and `nav-back` CSS classes from [Directional Navigation](references/css-recipes.md#directional-navigation) produce horizontal slides. For simpler apps where directional motion isn't needed, a bare `<ViewTransition default="none">` wrapper with `enter="fade-in"` / `exit="fade-out"` works too.

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

+

+ This also becomes the single place to adjust if you add new transition types later.

+ **Rules:**

+

+ - Always pair `enter` with `exit` — without an exit animation, the old page disappears instantly while the new one animates in.

+ - Always include `default: "none"` in type map objects and `default="none"` on the component — otherwise it fires on every transition.

+ - Place the directional `<ViewTransition>` in each page component, not in a layout. Layouts persist across navigations and never trigger enter/exit.

+ - Only use directional slides for hierarchical navigation or ordered sequences (prev/next). Lateral/sibling navigation (tab-to-tab) should use a bare `<ViewTransition>` (cross-fade) or `default="none"`.

+

+ For every `<Suspense>` boundary identified in Step 1, wrap the fallback and content in separate `<ViewTransition>`s:

+

+ This example uses `slide-down` / `slide-up` for directional vertical motion. For a simpler reveal, a bare `<ViewTransition>` around the `<Suspense>` gives a cross-fade with zero configuration. Choose based on the spatial meaning described in the main skill.

+ **Rules:**

+

+ - Always use `default="none"` on the content `<ViewTransition>` to prevent re-animation on revalidation or unrelated transitions.

+ - Use simple string props (not type maps) on Suspense `<ViewTransition>`s — Suspense resolves fire as separate transitions with no type, so type-keyed props won't match.

+ - A fallback/content `share` pair morphs between snapshots. Use it only when that interpolation is desired and does not distort layout or geometry.

+ - 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 `<Suspense>` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](references/patterns.md#suspense-reveal-flicker).

+

+ For every shared visual element identified in Step 1, add matching named `<ViewTransition>` wrappers on both the source and target views:

+

+ // On the source view (e.g., list/grid page)

+ // On the target view (e.g., detail page) — same name

+ The `share="morph"` class uses the [Shared Element Morph](references/css-recipes.md#shared-element-morph) recipe (controlled duration + motion blur). For a simpler cross-fade, use `share="auto"` (browser default).

+ When list items contain shared elements, compose both patterns with two nested `<ViewTransition>` 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).

+ **Rules:**

+ - Names must be globally unique — use prefixes like `photo-${id}`.

+ - Add `default="none"` on list-side shared elements to prevent per-item cross-fades on filter/search updates.

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

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

+ - Does the VT mount/unmount on this navigation, or does it stay mounted (same-route)?

+ - Do persistent elements stay static (not sliding with page content)?

+ If any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](references/troubleshooting.md).

+ For Next.js-specific implementation steps (`transitionTypes` on `<Link>`, prefetch behavior, and same-route dynamic segments), see [nextjs.md](references/nextjs.md).

+ Use the official [React `<ViewTransition>` reference](https://react.dev/reference/react/ViewTransition) for API mechanics. This file collects reusable implementation patterns and failure modes from production apps.

+

+ `useDeferredValue` makes filter updates a transition, activating `<ViewTransition>`:

+

+ Per-item `<ViewTransition name={...}>` inside a deferred list triggers cross-fades on every keystroke. Fix with `default="none"`:

+ ```tsx

+ {

+ filteredItems.map((item) => (

+ <ViewTransition

+ key={item.id}

+ name={`item-${item.id}`}

+ share="morph"

+ default="none"

+ >

+ <ItemCard item={item} />

+ </ViewTransition>

+ ));

+ }

+ ```

+

+ Toggle between grid and detail view with shared element morph:

+

+ ## Type-Safe Transition Helpers

+

+ Use `as const` arrays and derived types to prevent ID clashes:

+

+ ```tsx

+ const transitionTypes = [

+ "default",

+ "transition-to-detail",

+ "transition-to-list",

+ ] as const;

+ const animationTypes = [

+ "auto",

+ "none",

+ "animate-slide-from-left",

+ "animate-slide-from-right",

+ ] as const;

+

+ type TransitionType = (typeof transitionTypes)[number];

+ type AnimationType = (typeof animationTypes)[number];

+ type TransitionMap = { default: AnimationType } & Partial<

+ Record<Exclude<TransitionType, "default">, AnimationType>

+ >;

+

+ export function HorizontalTransition({

+ children,

+ enter,

+ exit,

+ }: {

+ children: React.ReactNode;

+ enter: TransitionMap;

+ exit: TransitionMap;

+ }) {

+ return (

+ <ViewTransition enter={enter} exit={exit}>

+ {children}

+ </ViewTransition>

+ );

+ }

+ ```

+

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

+ Use `key` when content identity changes (state resets). Omit for cross-fades (tabs, panels, carousel).

+

+ Pull 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 `<ViewTransition default="none">` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](references/css-recipes.md#persistent-element-isolation)).

+ - **Persistent chrome** (nav, sidebar, player bar): `<nav style={{ viewTransitionName: 'persistent-nav' }}>` + isolation CSS. `<ViewTransition default="none">` works too, but its auto-name can't take `z-index`/backdrop `display:none` — hand-name when you need those.

+ - **Floating elements** (popovers, menus): left open, they're captured in `root` and flicker on settle. Real name + isolation ([Floating Element Isolation](references/css-recipes.md#floating-element-isolation-popovers-menus-tooltips-control-clusters)). A static name is fine if only one is mounted (`unmountOnHide`); native top-layer (`popover`/`<dialog>`) settle-flicker is a browser limit.

+ - **Naming an interactive element has a cost:** named participants are skipped by hit-testing while a transition runs ([csswg#10930](https://github.com/w3c/csswg-drafts/issues/10930)) — clicks and hover fall through to whatever is beneath. Portal named popovers/menus; rendered inline in a clickable row, mid-transition clicks activate the row and read as outside-clicks that close the popover.

+ - **Third-party floating components** (toast libraries, portals you don't render): put the name on an always-mounted wrapper you own — `<div style={{ viewTransitionName: 'toaster' }} className="pointer-events-none fixed inset-0">`. Library containers often unmount when empty, so naming them directly leaves the group unpinned exactly when a toast appears mid-transition. Name a dialog's backdrop separately from its panel so each pins independently.

+

+ ## Suspense reveal flicker

+

+ An element rendered in **both** the fallback and the content flickers (opacity dip) on reveal — it fades against itself. Not a morph. **Fix: render it outside the `<Suspense>` boundary** (mount once, above it), or pin it with a `view-transition-name`.

+

+ <h1>{title}</h1>

+ <Suspense fallback={<BodySkeleton />}><Body /></Suspense>

+ Don't put a manual `viewTransitionName` on the root DOM node inside `<ViewTransition>` — React's auto-name overrides it.

+

+ ## Sliding Indicator (tabs)

+

+ One shared-name indicator rendered under the **active** tab morphs between positions on change (slide the group, disable old/new — see [Sliding Indicator](references/css-recipes.md#sliding-indicator-tab-underline--segmented-pill)). Render it only under the active tab so exactly one element holds `indicatorName`; use a distinct `indicatorName` per tab strip. Trigger the state change inside `startTransition` so the move animates. Whatever owns `active` drives it — local state here, routing in Next (see [Routing-Driven Tabs](references/nextjs.md#routing-driven-tabs)).

+

+ ```tsx

+ import { useState, useTransition, ViewTransition } from "react";

+

+ export function Tabs({ tabs, indicatorName = "tab-indicator" }) {

+ const [active, setActive] = useState(tabs[0].value);

+ const [, startTransition] = useTransition();

+ return (

+ <nav>

+ {tabs.map((t) => (

+ <button

+ key={t.value}

+ type="button"

+ aria-current={active === t.value ? "page" : undefined}

+ onClick={() => startTransition(() => setActive(t.value))}

+ >

+ <span>{t.label}</span>

+ {active === t.value && (

+ <ViewTransition name={indicatorName} share="tab-underline">

+ <span className="active-underline" aria-hidden />

+ </ViewTransition>

+ )}

+ </button>

+ ))}

+ </nav>

+ );

+ Because the state change is a transition, if the newly-active tab renders suspending content the whole update — indicator **and** `aria-current` — waits for it to commit, and the strip feels dead on click. Give the controls an immediate value with `useOptimistic` (drive `aria-current` from it) so feedback is instant while the content streams. The routing variant ([Routing-Driven Tabs](references/nextjs.md#routing-driven-tabs)) does exactly this: optimistic `aria-current`, committed `active` for the bar.

+ ## Layout Displacement Morph

+ Only content inside an activated boundary animates position — everything else teleports to its new layout spot. When a list grows or shrinks, wrap the sibling content below it so it glides instead of jumping:

+ ```jsx

+ <FavoritesList /> {/* rows enter/exit */}

+ <ViewTransition> {/* bare: update enabled */}

+ <section>

+ <h2>You Might Also Like</h2>

+ <Recommendations />

+ </section>

+ </ViewTransition>

+ ```

+

+ The section — heading included — morphs as one group when rows above are added or removed. Nothing inside the section changed; the _displacement_ is the update.

+

+ - React only measures boundaries that are direct children of nodes along the changed path — a VT buried under an extra wrapper element won't activate. Place the boundary as a direct sibling of the changing content.

+ - Sometimes the better fix is no morph at all: pad fixed-size lists to a constant slot count with invisible fillers so the grid never changes height and nothing below it moves.

+ - `default="none"` disables exactly this morph — it turns off `update`. Named/shared elements get `default="none"`; displaced siblings and keyed list items stay bare or set `update="auto"`.

+

+

+ // Usage: toggle with startTransition

+ <button onClick={() => startTransition(() => setOpen(o => !o))}>Toggle</button>

+ <AnimatedCollapse open={open}><SectionContent /></AnimatedCollapse>

+ ## Composing with Activity

+ `Activity` is orthogonal to view transitions: it preserves the state of a hidden subtree, `ViewTransition` animates it. Compose them for an in-page show/hide (drawer, panel, tab body) that keeps its scroll/form state while it animates in and out:

+

+ Only reach for Activity when there's state worth preserving — a stateless element (e.g. the sliding indicator above) gains nothing from it. In Next.js, layout-hosted chrome already persists across navigations without Activity (see [nextjs.md](references/nextjs.md#layout-level-viewtransition)).

+

+ `useOptimistic` values update before the transition snapshot, excluding them from animation. Use for controls (labels); use committed state for animated content:

+ ```tsx

+ const [sort, setSort] = useState("newest");

+ const [optimisticSort, setOptimisticSort] = useOptimistic(sort);

+

+ function cycleSort() {

+ const nextSort = getNextSort(optimisticSort);

+ startTransition(() => {

+ setOptimisticSort(nextSort); // before snapshot — no animation

+ setSort(nextSort); // between snapshots — animates

+ });

+ }

+

+ <button>Sort: {LABELS[optimisticSort]}</button>;

+ {

+ items.sort(comparators[sort]).map((item) => (

+ <ViewTransition key={item.id}>

+ <ItemCard item={item} />

+ </ViewTransition>

+ ));

+ }

+ ```

+

+ Imperative control via `onEnter`, `onExit`, `onUpdate`, `onShare`. Return a cleanup function to cancel your animation when the transition finishes. `onShare` takes precedence over `onEnter`/`onExit`.

+ The `instance` object: `instance.old`, `instance.new`, `instance.group`, `instance.imagePair`, `instance.name`.

+ The `types` array (second argument) lets you vary animation based on transition type.

+

+ | Interaction | Duration |

+ | ------------------------------------ | --------- |

+ | Direct toggle (expand/collapse) | 100–200ms |

+ | Route transition (slide) | 150–250ms |

+ | Suspense reveal (skeleton → content) | 200–400ms |

+ | Shared element morph | 300–500ms |

+ # Troubleshooting

+ **VT not activating:** Ensure `<ViewTransition>` comes before any DOM node and the state update is inside `startTransition`. A raw `viewTransitionName` only isolates an element; it does not activate a React view transition.

+ **"Two ViewTransition components with the same name":** Names must be globally unique. Use IDs such as `name={`hero-${item.id}`}`. If a reusable component appears in multiple surfaces at once, move the name to the specific consumer or make it conditional.

+ **Unrelated content crossfades:** A bare VT uses the browser crossfade for every trigger. Set `default="none"` and opt in only to the triggers that boundary should handle.

+ **Scrolling hangs while a transition animates:** the `::view-transition` overlay is `position: fixed` and its snapshots don't scroll — a browser limitation, not fixable in React (skipping snaps to the end). Keep reveal durations short; for scroll-driven UI use gesture transitions (experimental `useSwipeTransition`, if available).

+ **Open popover flickers when a background transition settles:** it's captured in `root`. Give it a real `view-transition-name` + isolation (not `none`) — see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations).

+ **Popover closes or goes dead when clicked mid-transition:** named participants are skipped by hit-testing while a transition runs; clicks land on what's beneath and read as outside-clicks. Portal the popover (see [Isolate Elements from Parent Animations](references/patterns.md#isolate-elements-from-parent-animations)); brief dead clicks during the transition remain — that's the price of the name.

+

+ **Shared morph silently not firing:** `share` resolved to `none`. Either the VT has `default="none"` with no explicit `share` prop, or `share` is type-keyed and the navigation never adds the type — the link needs `transitionTypes` (or `addTransitionType` in the transition).

+

+ **Shared morph competes with a page fade:** A fading page exit dissolves the source while it is morphing. Remove that exit or use motion that preserves the shared element's continuity.

+

+ **An enter animation runs even though Suspense never showed its fallback:** The content-side VT became the topmost entering subtree during navigation. At that call site, add a host DOM element immediately outside `Suspense`. The host suppresses the nested enter during warm navigation but remains mounted so the VT can enter on a later fallback-to-content reveal. Keep the host outside `Suspense`, not inside the reusable crossfade; do nothing when a direct host already exists.

+

+ **Section below a list teleports instead of gliding:** it's outside any activated boundary, its VT has `default="none"` (which disables `update`), or it isn't an immediate sibling of the changing content. See [Layout Displacement Morph](references/patterns.md#layout-displacement-morph).

+

+ **`router.back()` and browser back/forward skip the directional slide:** traversals carry no transition types, so type-keyed maps resolve to `default` — untyped shared-element morphs still apply. Use `router.push()` for typed animations.

+

+ **`flushSync` skips animations:** Use `startTransition` instead.

+

+ **Only updates animate (no enter/exit):** Without `<Suspense>`, React treats swaps as updates. Conditionally render the VT itself, or wrap in `<Suspense>`.

+

+ **Suspense reveal does not animate:** Suspense resolves in a separate transition without navigation types. Use string `enter`/`exit` props rather than a type map.

+

+ **Layout VT prevents page VTs from animating:** Nested VTs skip their own enter/exit when they mount or unmount as one unit with a parent VT. Keep route boundaries in pages, not a layout wrapping `{children}`. React has experimental upstream `parentEnter`/`parentExit` work ([PR #36690](https://github.com/facebook/react/pull/36690)), but those props are not currently available in the Next.js client runtime; do not recommend them in a Next.js app unless the installed runtime and docs explicitly include them.

+

+ **Same-route content does not animate with `update`:** Nested VTs can own the mutation before an outer boundary sees it. For a real identity change, use `key` with a stable `name` and `share` instead.

+

+ **List reorder not animating with `useOptimistic`:** Optimistic values resolve before snapshot. Use committed state for list order.

+

+ **Hash fragments cause scroll jumps:** Navigate without hash; scroll programmatically after navigation.

+ **Backdrop-blur flickers:** Use the [Backdrop-Blur Workaround](references/css-recipes.md#backdrop-blur-workaround).

+ **`border-radius` lost during transitions:** Apply `border-radius` directly to the captured element.

+ **Skeleton controls slide away:** Give matching controls the same `viewTransitionName`.

+

+ **Batching:** Multiple updates during animation are batched. A→B→C→D becomes B→D.

+

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

+ This file contains the complete CSS recipe set for the patterns in this skill. Copy only what the app needs.

+

+ ---

+

+ ---

+

+ Usage: `<ViewTransition enter="fade-in" exit="fade-out" />`

+

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

+

+ ---

+

+ Usage:

+

+ ```jsx

+ <Suspense

+ fallback={

+ <ViewTransition exit="slide-down">

+ <Skeleton />

+ </ViewTransition>

+ }

+ >

+ <ViewTransition default="none" enter="slide-up">

+ <Content />

+ </ViewTransition>

+ </Suspense>

+ ```

+

+ ---

+

+ ### Separate Enter/Exit Classes

+ ::view-transition-new(.slide-from-right) {

+ ::view-transition-old(.slide-to-left) {

+ --slide-offset: -60px;

+

+ ::view-transition-new(.slide-from-left) {

+ ::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;

+ }

+ ### Single-Class Approach

+ ::view-transition-old(.nav-forward) {

+ ::view-transition-new(.nav-forward) {

+ --slide-offset: 60px;

+

+ ::view-transition-old(.nav-back) {

+ ::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;

+ }

+ ---

+

+

+

+ Usage: `<ViewTransition name={`product-${id}`} share="morph" />`

+

+ Usage: `<ViewTransition name={`title-${id}`} share="text-morph" />`

+

+ ---

+

+

+ Usage: `<ViewTransition enter="scale-in" exit="scale-out" />`

+

+ ---

+

+ ## Interactivity During Transitions

+

+ The `::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:

+

+ ```css

+ ::view-transition {

+ pointer-events: none;

+ }

+ ```

+

+ Trade-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](references/patterns.md#isolate-elements-from-parent-animations)).

+

+ ---

+

+ ## No Root Cross-Fade (Live Root)

+

+ The 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):

+

+ ```css

+ ::view-transition-old(root) {

+ display: none;

+ }

+ ::view-transition-new(root) {

+ animation: none;

+ }

+ ```

+

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

+

+ Pairs well with enter-only reveals: skip the fallback-exit VT entirely (`<ViewTransition enter="auto" default="none">` around the content, nothing on the skeleton) — the skeleton snaps out live while the content fades in.

+

+ ---

+

+ Layer multiple pinned groups with z-index tiers — chrome at `100`, toasts/overlays that must beat everything at `200`.

+

+ For elements with `backdrop-filter`, hide the old snapshot to avoid flash:

+

+ ### Floating Element Isolation (popovers, menus, tooltips, control clusters)

+

+ Same 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:

+

+ ```css

+ ::view-transition-group(popover) {

+ animation: none;

+ z-index: 100;

+ }

+ ::view-transition-old(popover),

+ ::view-transition-new(popover) {

+ animation: none;

+ }

+ ```

+

+ ### Sliding Indicator (tab underline / segmented pill)

+

+ One shared-name indicator morphs between positions. Slide the group; disable old/new so the solid bar slides instead of cross-fading:

+

+ ```css

+ ::view-transition-group(.tab-underline) {

+ animation-duration: 220ms;

+ animation-timing-function: cubic-bezier(0.5, 0, 0.2, 1);

+ }

+ ::view-transition-old(.tab-underline),

+ ::view-transition-new(.tab-underline) {

+ animation: none;

+ height: 100%;

+ }

+ ```

+

+ ---

+

+ `<ViewTransition>` 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.

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

+ Because every link click is a transition, any VT with `default="auto"` fires on **every** navigation — use `default="none"` to prevent competing animations.

+

+ For unexpected or broken animation behavior, see [troubleshooting.md](references/troubleshooting.md).

+

+ ---

+

+ When following [implementation.md](references/implementation.md), apply these additions:

+ **Step 4:** Use `transitionTypes` on `<Link>` — 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).

+ **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).

+

+ ---

+

+ ## Layout-Level ViewTransition

+

+ **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).

+

+ A bare `<ViewTransition>` in layout works only if pages have **no** VTs of their own.

+

+ **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](references/patterns.md#composing-with-activity)).

+

+ ---

+

+ ## The `transitionTypes` Prop on `next/link`

+

+ No wrapper component needed, works in Server Components:

+

+ <Link href="/products/1" transitionTypes={["transition-to-detail"]}>

+ View Product

+ </Link>

+ Replaces the manual pattern of `onNavigate` + `startTransition` + `addTransitionType` + `router.push()`. Reserve manual `startTransition` for non-link interactions (buttons, forms).

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

+ ---

+ ## When Content Must Be Ready

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

+ When an animation depends on dynamic destination content, use Next.js prefetching and caching to make that content available ahead of time. `<Link>` 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.

+

+ <Link href={nextHref} prefetch={true} transitionTypes={["nav-forward"]}>

+ Next

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

+ Verify directional transitions in a production build with a cold client cache. Development mode does not run automatic `<Link>` prefetching.

+ See the Next.js [View Transitions guide](https://nextjs.org/docs/app/guides/view-transitions) and [Prefetching guide](https://nextjs.org/docs/app/guides/prefetching).

+ ---

+

+ ## Programmatic Navigation

+

+ ```tsx

+ "use client";

+

+ import { useRouter } from "next/navigation";

+

+ function DetailButton({ href }: { href: string }) {

+ const router = useRouter();

+

+ return (

+ <button

+ onClick={() => router.push(href, { transitionTypes: ["nav-forward"] })}

+ >

+ Open

+ </button>

+ );

+ }

+ ```

+

+ The `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.

+

+ ---

+

+ For 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`:

+ ```tsx

+ "use client";

+

+ import { useRouter } from "next/navigation";

+ import { startTransition } from "react";

+

+ function SortControl() {

+ const router = useRouter();

+

+ function handleSort(sort: string) {

+ startTransition(() => {

+ router.replace(`?sort=${sort}`);

+ });

+ }

+

+ return <button onClick={() => handleSort("newest")}>Newest</button>;

+ }

+ ```

+

+ List items wrapped in `<ViewTransition key={item.id}>` will animate reorder. This is the server-component alternative to the client-side [Searchable Grid](references/patterns.md#searchable-grid-with-usedeferredvalue) pattern.

+

+ For 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`](references/patterns.md#exclude-elements-with-useoptimistic).

+

+ ---

+

+ ## Routing-Driven Tabs

+

+ The generalized sliding indicator ([Sliding Indicator](references/patterns.md#sliding-indicator-tabs)) driven by navigation instead of local state: tabs are `<Link>`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.

+

+ ```tsx

+ "use client";

+ import Link from "next/link";

+ import { useOptimistic, useTransition, ViewTransition } from "react";

+

+ export function Tabs({ tabs, active, indicatorName = "tab-indicator" }) {

+ const [optimisticActive, setOptimisticActive] = useOptimistic(active);

+ const [, startTransition] = useTransition();

+ return (

+ <nav>

+ {tabs.map((t) => (

+ <Link

+ key={t.value}

+ href={t.href}

+ scroll={false}

+ aria-current={optimisticActive === t.value ? "page" : undefined}

+ onNavigate={() => startTransition(() => setOptimisticActive(t.value))}

+ >

+ <span>{t.label}</span>

+ {active === t.value && (

+ <ViewTransition name={indicatorName} share="tab-underline">

+ <span className="active-underline" aria-hidden />

+ </ViewTransition>

+ )}

+ </Link>

+ ))}

+ </nav>

+ );

+ }

+ ```

+

+ ---

+

+ ---

+

+ ## `loading.tsx` as Suspense Boundary

+

+ Next.js `loading.tsx` is an implicit `<Suspense>` boundary. Wrap the skeleton in `<ViewTransition exit="...">` in `loading.tsx`, and the content in `<ViewTransition enter="..." default="none">` in the page:

+

+ ```tsx

+ // loading.tsx

+ <ViewTransition exit="slide-down"><PhotoGridSkeleton /></ViewTransition>

+

+ // page.tsx

+ <ViewTransition enter="slide-up" default="none"><PhotoGrid photos={photos} /></ViewTransition>

+ ```

+

+ Same rules as explicit `<Suspense>`: use simple string props (not type maps) since Suspense reveals fire without transition types.

+

+ ---

+

+ {

+ products.map((product) => (

+ <Link

+ key={product.id}

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

+ ));

+ }

+ </ViewTransition>;

+ If the pair's `share` is type-keyed (or classed via CSS that expects a type), every `<Link>` 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.

+

+ ---

+

+ When 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`:

+ name="collection-content"

+ - `key={slug}` forces unmount/remount on change

+ - The stable `name` pairs the outgoing and incoming containers; `share="auto"` creates the crossfade

+ - VT inside `<Suspense>` (without keying Suspense) keeps old content visible during loading

+

+ - `<ViewTransition>` works in both Server and Client Components

+ - `<Link transitionTypes>` works in Server Components — no `'use client'` needed

+ - `router.push(..., { transitionTypes })`, `addTransitionType`, and `startTransition` require Client Components