`s between list and VT. ### 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 `` so it glides instead of jumping. See [Layout Displacement Morph](references/patterns.md#layout-displacement-morph). ### Composing Shared Elements with List Identity Shared elements and list identity are independent concerns — don't confuse one for the other. When a list item contains a shared element (e.g., an image that morphs into a detail view), use two nested `` boundaries: ```jsx {items.map(item => ( {/* list identity */} {/* shared element */}

{item.name}

))} ``` 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. ### Force Re-Enter with `key` ```jsx ``` **Caution:** If wrapping ``, changing `key` remounts the boundary and refetches. ### Suspense Fallback to Content Simple cross-fade: ```jsx }> ``` Directional reveal: ```jsx }> ``` For more patterns, see [references/patterns.md](references/patterns.md). --- ## How Multiple VTs Interact 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"`. ### Two Patterns Coexist **Pattern A — Directional slides:** Type-keyed VT on each page, fires during navigation. **Pattern B — Suspense reveals:** Simple string props, fires when data loads (no type). They coexist because they fire at different moments. `default="none"` on both prevents cross-interference. Always pair `enter` with `exit`. Place directional VTs in page components, not layouts. ### Nested VT Limitation When a parent VT 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. --- ## Next.js Integration For Next.js integration (`transitionTypes` on `next/link` and `useRouter`, App Router patterns, Server Components), see [references/nextjs.md](references/nextjs.md). --- ## Accessibility 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. --- # Implementation Workflow Follow these steps in order when adding view transitions to an app. Each step builds on the previous one. Use 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. ## Step 1: Audit the App Before writing any code, scan the codebase thoroughly. Search for: - **Every `` and `router.push`** — these are your navigation triggers. Open every file that contains one. - **Every `` 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`. Then classify every navigation and produce a navigation map: ``` | Route | Navigates to | Direction | VT pattern | |-----------------|----------------------|--------------|-----------------------| | / | /detail/[id] | forward | directional slide | | /detail/[id] | / | back | directional slide | | /detail/[id] | /detail/[other] | sequential | directional slide (ordered prev/next) or key+share crossfade | | /tab/[a] | /tab/[b] | lateral | key+share crossfade | | (Suspense) | (content loads) | — | slide-up reveal | ``` For each shared element (`name` prop), note every navigation where a pair forms and where it doesn't — this determines whether you need `enter`/`exit` as a fallback alongside `share`. ## Step 2: Add CSS Recipes Choose 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. Customize timing after the structure works. Keep ordinary crossfades opacity-only; scope blur to a specific shared morph when it is intentional. ## Step 3: Isolate Persistent Elements For every persistent element identified in Step 1, add a `viewTransitionName` style to pull it out of the page content's transition snapshot: ```jsx

...

``` Then 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. 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. ## Step 4: Add Directional Page Transitions For hierarchical navigations identified in Step 1, tag the navigation direction using `addTransitionType` inside `startTransition`: ```jsx startTransition(() => { addTransitionType('nav-forward'); router.push('/detail/1'); }); ``` Then wrap each **page component** (not layout) in a type-keyed ``: ```jsx

...page content...

``` The `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. Extract this into a reusable component so every page doesn't repeat the verbose type map: ```jsx export function DirectionalTransition({ children }: { children: React.ReactNode }) { return ( {children} ); } ``` 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 `` 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 `` (cross-fade) or `default="none"`. ## Step 5: Add Suspense Reveals For every `` boundary identified in Step 1, wrap the fallback and content in separate ``s: ```jsx } > ``` This 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. **Rules:** - Always use `default="none"` on the content `` to prevent re-animation on revalidation or unrelated transitions. - 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. - 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 `` boundary (or pin it), so it isn't in both. See [Suspense reveal flicker](patterns.md#suspense-reveal-flicker). ## Step 6: Add Shared Element Transitions For every shared visual element identified in Step 1, add matching named `` wrappers on both the source and target views: ```jsx // 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](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 `` 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. ## Step 7: Verify Each Navigation Path 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)? - For named VTs: does a shared pair form? If not, does `enter`/`exit` provide a fallback? - Does `default="none"` block an animation you actually want? - Do persistent elements stay static (not sliding with page content)? - Do Suspense reveals animate independently from directional navigations? If any path produces no animation or competing animations, use the symptom-driven [troubleshooting guide](troubleshooting.md). For Next.js-specific implementation steps (`transitionTypes` on ``, prefetch behavior, and same-route dynamic segments), see [nextjs.md](nextjs.md). --- # Patterns and Guidelines Use 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. ## Searchable Grid with `useDeferredValue` `useDeferredValue` makes filter updates a transition, activating ``: ```tsx 'use client'; import { useDeferredValue, useState, ViewTransition, Suspense } from 'react'; export default function SearchableGrid({ itemsPromise }) { const [search, setSearch] = useState(''); const deferredSearch = useDeferredValue(search); return ( <> setSearch(e.currentTarget.value)} /> }> ); } ``` Per-item `` inside a deferred list triggers cross-fades on every keystroke. Fix with `default="none"`: ```tsx {filteredItems.map(item => ( ))} ``` ## Card Expand/Collapse with `startTransition` Toggle between grid and detail view with shared element morph: ```tsx 'use client'; import { useState, useRef, startTransition, ViewTransition } from 'react'; export default function ItemGrid({ items }) { const [expandedId, setExpandedId] = useState(null); const scrollRef = useRef(0); return expandedId ? ( i.id === expandedId)} onClose={() => { startTransition(() => { setExpandedId(null); setTimeout(() => window.scrollTo({ behavior: 'smooth', top: scrollRef.current }), 100); }); }} /> ) : (

{items.map(item => ( { scrollRef.current = window.scrollY; startTransition(() => setExpandedId(item.id)); }} /> ))}

); } ``` ## 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, AnimationType>>; export function HorizontalTransition({ children, enter, exit }: { children: React.ReactNode; enter: TransitionMap; exit: TransitionMap; }) { return {children}; } ``` ## Cross-Fade Without Remount Omit `key` to trigger an update (cross-fade) instead of exit + enter. Avoids Suspense remount/refetch: ```jsx ``` Use `key` when content identity changes (state resets). Omit for cross-fades (tabs, panels, carousel). ## Isolate Elements from Parent Animations 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 `` (no CSS) or CSS (needed for `z-index`/`display` control — see [css-recipes.md](css-recipes.md#persistent-element-isolation)). - **Persistent chrome** (nav, sidebar, player bar): `

` + isolation CSS. `` 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](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`/`

You Might Also Like

` → `