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.

仓库: ChloeVPin/candy-skills
最近来源活动: 2026年6月29日 23:03
检测到的 SKILL.md 语言: 英语
星标: 0
分支: 0

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

返回搜索返回安装

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/