react-view-transitions

IMPLEMENT smooth, native-feeling animations using React's View Transition API (`<ViewTransition>` component, `addTransitionType`, and CSS view transition pseudo-elements). Use for page transitions, route changes, shared element animations, enter/exit animations, list reorder, directional navigation. Browser support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers. Never call `document.startViewTransition` directly, use `<ViewTransition>` component.

Jump to install

Repository: ChloeVPin/candy-skills
Last source activity: June 29, 2026 at 23:03
Detected SKILL.md language: English
Stars: 0
Forks: 0

Install options

The review-first prompt is selected by default. You can switch to a direct command or download a local copy.

Review the source files

Read SKILL.md and any companion files shown by SkillsMP before deciding whether to install.

Back to search Back to installation

name	React View Transitions
description	IMPLEMENT smooth, native-feeling animations using React's View Transition API (`<ViewTransition>` component, `addTransitionType`, and CSS view transition pseudo-elements). Use for page transitions, route changes, shared element animations, enter/exit animations, list reorder, directional navigation. Browser support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful degradation on unsupported browsers. Never call `document.startViewTransition` directly, use `<ViewTransition>` component.
license	MIT
metadata	{"author":"vercel","version":"2.0.0","last_updated":"2026-06-28T00:00:00.000Z"}
stacks	["React 19.2","Next.js 16 (App Router)"]
tags	["animations","view-transitions","react-19"]
related_skills	["responsive-layout-math","accessibility-audit-protocol","component-architecture-patterns","react-best-practices"]
category	react
version	2.0.0

React View Transitions

IDENTIFY: When to Activate

Activate when user wants to add:

Page transitions between routes
Shared element animations (element morphs between screens)
List reorder animations
Enter/exit animations for components appearing/disappearing
Directional navigation (forward/back transitions)
Or mentions: "view transitions", "startViewTransition", "ViewTransition", "animate between pages"

DECIDE: Animation Pattern Selection

For every transition opportunity, implement ALL applicable patterns, in this priority order:

Priority 1: Shared element, element appears on both source and destination pages
  → Use <ViewTransition name="unique-id" share="morph">
  → Communicates: "Same thing, going deeper"

Priority 2: Suspense reveal, content loads async
  → Use <ViewTransition enter="fade-in" default="none">
  → Communicates: "Data loaded"

Priority 3: List identity, items rearranged
  → Use <ViewTransition key={item.id}> per item
  → Communicates: "Same items, new arrangement"

Priority 4: State change, component enters/exits
  → Use <ViewTransition enter="slide-in" exit="slide-out">
  → Communicates: "Something appeared/disappeared"

Priority 5: Route change, navigating between pages
  → Use type-keyed ViewTransition with addTransitionType
  → Communicates: "Going to a new place"

ANIMATION STYLE SELECTION

Navigation Context	Animation	Why
Hierarchical (list → detail)	Directional: `nav-forward` / `nav-back`	Communicates spatial depth
Lateral (tab → tab)	Fade (`default="none"`) or no animation	No depth to communicate
Suspense reveal	`enter`/`exit` string props	Content arriving
Background refresh	`default="none"`	Silent, no animation needed

EXECUTE: Implementation Workflow

Step 1: Audit Transition Opportunities

Identify ALL of these before writing code:

Elements appearing on multiple pages (shared element candidates)
Navigation paths (hierarchical vs lateral vs back)
Suspense boundaries (content loading states)
Lists that reorder
Components that mount/unmount conditionally

Step 2: Setup

// Source page, thumbnail
<ViewTransition name={`hero-image-${id}`} share="morph">
  <Image src="/thumb.jpg" />
</ViewTransition>

// Destination page, full size (same name)
<ViewTransition name={`hero-image-${id}`} share="morph">
  <Image src="/full.jpg" />
</ViewTransition>

// Wrapper component
export function DirectionalTransition({ children }: { children: React.ReactNode }) {
  return (
    <ViewTransition
      enter={{ 'nav-forward': 'slide-from-right', 'nav-back': 'slide-from-left', default: 'none' }}
      exit={{ 'nav-forward': 'slide-to-left', 'nav-back': 'slide-to-right', default: 'none' }}
      default="none"
    >
      {children}
    </ViewTransition>
  );
}

// Trigger navigation with type
startTransition(() => {
  addTransitionType('nav-forward');
  router.push('/detail/1');
});

// Content reveal, separate from navigation transitions
<ViewTransition enter="fade-in" default="none">
  <Suspense fallback={<Skeleton />}>
    <Content />
  </Suspense>
</ViewTransition>

{items.map(item => (
  <ViewTransition key={item.id} default="none">
    <ItemCard item={item} />
  </ViewTransition>
))}

{items.map(item => (
  <ViewTransition key={item.id} default="none">                   {/* list identity */}
    <ViewTransition name={`item-image-${item.id}`} share="morph" default="none"> {/* shared element */}
      <Image src={item.image} />
    </ViewTransition>
  </ViewTransition>
))}

/* ALWAYS include reduced motion */
@media (prefers-reduced-motion: reduce) {
  ::view-transition-group(*),
  ::view-transition-old(*),
  ::view-transition-new(*) {
    animation: none !important;
  }
}

1. ALWAYS set default="none" on EVERY ViewTransition, prevents cross-fade on Suspense/resync
2. ALWAYS use unique names for shared elements, duplicate names break morphs
3. ALWAYS pair enter with exit, asymmetric animations confuse users
4. NEVER call document.startViewTransition, use <ViewTransition> component
5. NEVER write custom animation keyframes, use CSS recipes from references/
6. ALWAYS include reduced motion CSS in global stylesheet
7. ALWAYS keep <ViewTransition> as the outermost wrapper, enter/exit activated only when VT is first DOM node

- router.back() and browser back/forward do NOT trigger view transitions
  → Use router.push() with explicit URL instead
- Nested VT enter/exit: parent exit suppresses child enter/exit
  → Only outermost VT animates during page exits
- Types available during navigation but NOT during Suspense reveals
  → Use type maps for page enter/exit, simple strings for Suspense

Anti-Pattern	Why Wrong	Fix
`document.startViewTransition()`	Raw API bypasses React's lifecycle	Use `<ViewTransition>` component
No `default="none"`	Every Suspense resolve triggers cross-fade	ALWAYS set `default="none"`
Duplicate shared element names	Two VTs with same name mount → morph breaks	Use unique IDs: `photo-${id}`
Directional slides for lateral nav	Falsely implies spatial depth	Use fade or no animation
Custom animation keyframes from scratch	Inconsistent, harder to maintain	Use CSS recipes from references/