# React View Transitions **Version 1.0.0** Vercel Engineering > **Note:** > 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. --- Use React's View Transition integration to communicate continuity, hierarchy, or content arrival. Do not add motion without a clear meaning. ## Read Current Documentation First The APIs are evolving. Use the official references instead of reproducing their API documentation from memory: - [React ``](https://react.dev/reference/react/ViewTransition) - [React `addTransitionType`](https://react.dev/reference/react/addTransitionType) - [Next.js View Transitions guide](https://nextjs.org/docs/app/guides/view-transitions) - [Next.js `` `transitionTypes`](https://nextjs.org/docs/app/api-reference/components/link#transitiontypes) - [Next.js `useRouter`](https://nextjs.org/docs/app/api-reference/functions/use-router) For Next.js, also read the matching guide under `node_modules/next/dist/docs/`. The installed version is authoritative for configuration and signatures. ## Workflow 1. Audit the update trigger, participating VTs, mount/persist/unmount behavior, Suspense boundaries, and persistent chrome. 2. Implement the smallest semantic pattern first. 3. Add only the CSS recipes that pattern needs. 4. Verify warm and cold navigation, history traversal, fallback reveals, unrelated updates, and reduced motion. For a whole-app rollout, follow [references/implementation.md](references/implementation.md). For focused work, load only the relevant reference: | Need | Reference | |---|---| | Production patterns | [references/patterns.md](references/patterns.md) | | Unexpected or broken animation behavior | [references/troubleshooting.md](references/troubleshooting.md) | | Next.js routing and prefetch behavior | [references/nextjs.md](references/nextjs.md) | | Reusable CSS | [references/css-recipes.md](references/css-recipes.md) | ## Choose by Meaning | Intent | Pattern | |---|---| | Same object across views | Matching `name` and `share` | | Data arrived | Suspense reveal | | Same items moved | Keyed item VTs with `update` enabled | | Component appeared/disappeared | `enter` / `exit` | | Hierarchical navigation | Type-keyed forward/back animation | | Same place, different content | Update or shared crossfade | Shared identity and list identity are separate. A list item containing a shared image can need an outer keyed VT for reorder and an inner named VT for the cross-route morph. ## Guardrails - Let React call `document.startViewTransition`; do not call it directly in React code. - State-driven VTs need a React Transition, Suspense, or deferred update. Ordinary `setState` does not activate them. - Treat `name` as global identity. It must be unique among simultaneously mounted elements. - `default="none"` disables unspecified triggers, including `update` and `share`; opt required triggers back in. - Type maps need a `default`. Suspense reveals happen in a later untyped transition, so reveal VTs normally use string props. - A raw `viewTransitionName` isolates an element; it does not start a transition. `viewTransitionName: "none"` is no isolation. - Keep route enter/exit boundaries in pages unless a persistent layout is intentionally the animated subject. - Prefer opacity-only crossfades. Reserve blur for a deliberate morph. - Always include reduced-motion CSS. ## Patterns Learned from Production Apps The detailed implementations live in the references; these are the cases most often missed: - **Optimistic controls:** update labels and pending styles optimistically, but keep named shared indicators tied to committed route state. - **Appended pages:** render the initial page normally and animate only pages appended after interaction. - **Layout displacement:** wrap the sibling that moves, not only the content whose size changed. - **Persistent and portaled UI:** isolate fixed chrome and floating surfaces with stable names. For third-party portals, name an always-mounted owner. - **Fallback/content duplicates:** move repeated headings and controls outside Suspense, or give them deliberate shared identity, to avoid an opacity dip. - **Live app shells:** disable the root snapshot animation when unnamed persistent chrome must stay live and interactive. ## Verification Check the behavior users see: - prefetched/warm navigation and cold/suspended navigation; - forward links, programmatic navigation, and browser back/forward; - every path where a shared pair should or should not form; - optimistic and committed states; - persistent chrome, open overlays, pointer interaction, and reduced motion; - revalidation and unrelated transitions, which should remain quiet. Use screenshots or recordings when timing, geometry, or flicker is the issue. --- # 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 Use the official guide's examples to decide what should animate. Then copy only the applicable sections from [css-recipes.md](css-recipes.md), which contains the complete recipe set for this skill. 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 [Choose by Meaning](../SKILL.md#choose-by-meaning). **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, revisit the relevant step. --- ## Common Mistakes - **Bare `` without props** — without `default="none"`, it fires the browser's default cross-fade on every transition (every navigation, every Suspense resolve, every revalidation). Always set `default="none"` and explicitly enable only the triggers you want. - **Directional `` in a layout** — layouts persist across navigations and never unmount/remount. `enter`/`exit` props won't fire on route changes. Place the outer type-keyed `` in each page component. - **Fade-out exit with shared element morphs** — the page dissolving conflicts with the morph. Use a directional slide exit instead. - **Copying every CSS recipe** — broad rules animate surfaces the app never intended to include. Start from the official example for the chosen pattern, then add only the focused recipes the audit requires. - **Missing `default: "none"` in type-keyed objects** — TypeScript requires a `default` key, and without it the fallback is `"auto"` which fires on every transition. - **Type maps on Suspense reveals** — Suspense resolves fire as separate transitions with no type. Type-keyed props won't match — use simple string props instead. - **Raw `viewTransitionName` CSS to trigger animations** — React only calls `document.startViewTransition` when `` components are in the tree. A bare `viewTransitionName` style is for isolating elements from a parent's snapshot, not for triggering animations. - **`update` trigger for same-route navigations** — nested VTs inside the content steal the mutation from the parent, so `update` never fires on the outer VT. Use `key` + `name` + `share` instead. - **Named VT in a reusable component** — if a component with a named VT is rendered in both a modal/popover *and* a page, both mount simultaneously and break the morph. Make the name conditional or move it to the specific consumer. - **`router.back()` for back navigation** — traversals carry no transition types, so type-keyed animations don't play (untyped morphs still can). Use `router.push()` with an explicit URL for a fully animated back affordance. --- 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): `