# Vercel React View Transitions > 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)… - **Type:** Skill - **Install:** `agentstack add skill-rolecraft-sh-skills-react-view-transitions` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [rolecraft-sh](https://agentstack.voostack.com/s/rolecraft-sh) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [rolecraft-sh](https://github.com/rolecraft-sh) - **Source:** https://github.com/rolecraft-sh/skills/tree/main/skills/react-view-transitions - **Website:** https://rolecraft-sh.github.io/rolecraft/ ## Install ```sh agentstack add skill-rolecraft-sh-skills-react-view-transitions ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # React View Transitions Animate 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. ## When to Animate Every `` should communicate a spatial relationship or continuity. If you can't articulate what it communicates, don't add it. Implement **all** applicable patterns from this list, in this order: | Priority | Pattern | What it communicates | |----------|---------|---------------------| | 1 | **Shared element** (`name`) | "Same thing — going deeper" | | 2 | **Suspense reveal** | "Data loaded" | | 3 | **List identity** (per-item `key`) | "Same items, new arrangement" | | 4 | **State change** (`enter`/`exit`) | "Something appeared/disappeared" | | 5 | **Route change** (layout-level) | "Going to a new place" | This 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. ### Choosing Animation Style | Context | Animation | Why | |---------|-----------|-----| | Hierarchical navigation (list → detail) | Type-keyed `nav-forward` / `nav-back` | Communicates spatial depth | | Lateral navigation (tab-to-tab) | Bare `` (fade) or `default="none"` | No depth to communicate | | Suspense reveal | `enter`/`exit` string props | Content arriving | | Revalidation / background refresh | `default="none"` | Silent — no animation needed | Reserve 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. --- ## Availability - **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. - **Without Next.js:** Install `react@canary react-dom@canary` (`ViewTransition` is not in stable React). - 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. Copy the CSS recipes from [references/css-recipes.md](references/css-recipes.md) into the global stylesheet — do not write your own animation CSS. --- ## Core Concepts ### The `` Component ```jsx import { ViewTransition } from 'react'; ``` React auto-assigns a unique `view-transition-name` and calls `document.startViewTransition` behind the scenes. Never call `startViewTransition` yourself. ### Animation Triggers | Trigger | When it fires | |---------|--------------| | **enter** | `` first inserted during a Transition | | **exit** | `` first removed during a Transition | | **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 | | **share** | Named VT unmounts and another with same `name` mounts in the same Transition | Only `startTransition`, `useDeferredValue`, or `Suspense` activate VTs. Regular `setState` does not animate. ### Critical Placement Rule `` only activates enter/exit if it appears **before any DOM nodes**: ```jsx // Works Content // Broken — div wraps the VT, suppressing enter/exit Content ``` --- ## Styling with View Transition Classes ### Props Values: `"auto"` (browser cross-fade), `"none"` (disabled), `"class-name"` (custom CSS), or `{ [type]: value }` for type-specific animations. ```jsx ``` If `default` is `"none"`, all triggers are off unless explicitly listed. ### CSS Pseudo-Elements - `::view-transition-old(.class)` — outgoing snapshot - `::view-transition-new(.class)` — incoming snapshot - `::view-transition-group(.class)` — container - `::view-transition-image-pair(.class)` — old + new pair See [references/css-recipes.md](references/css-recipes.md) for ready-to-use animation recipes. --- ## Transition Types 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: ```jsx startTransition(() => { addTransitionType('nav-forward'); addTransitionType('select-item'); router.push('/detail/1'); }); ``` Pass an object to map types to CSS classes. Works on `enter`, `exit`, **and** `share`: ```jsx ``` `enter` and `exit` don't have to be symmetric. For example, fade in but slide out directionally: ```jsx ``` **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 ( {children} ); } ``` ### `router.back()` and Browser Back Button `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. ### Types and Suspense Types 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. --- ## Shared Element Transitions Same `name` on two VTs — one unmounting, one mounting — creates a shared element morph: ```jsx startTransition(() => onSelect())} /> // 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. --- ## Common Patterns ### Enter/Exit ```jsx {show && ( )} ``` ### List Reorder ```jsx {items.map(item => ( ))} ``` Trigger inside `startTransition`. Avoid wrapper ``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 possible today; the experimental opt-in is the `parentEnter`/`parentExit` props ([react#36690](https://github.com/facebook/react/pull/36690), experimental channel only). --- ## Next.js Integration For Next.js setup (`experimental.viewTransition` flag, `transitionTypes` prop on `next/link`, 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, events API, troubleshooting. - **[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. ## Full Compiled Document For the complete guide with all reference files expanded: `AGENTS.md` ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [rolecraft-sh](https://github.com/rolecraft-sh) - **Source:** [rolecraft-sh/skills](https://github.com/rolecraft-sh/skills) - **License:** MIT - **Homepage:** https://rolecraft-sh.github.io/rolecraft/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-rolecraft-sh-skills-react-view-transitions - Seller: https://agentstack.voostack.com/s/rolecraft-sh - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.