Communitygithub.com

React View Transitions

Leitfaden zur Implementierung von flüssigen, nativen Animationen mit der React View Transition API (`<ViewTransition>`-Komponente, `addTransitionType` und CSS-View-Transition-Pseudoelementen).

Was ist React View Transitions?

Diese Skill-Anleitung beschreibt, wie du mit der nativen browserbasierten `document.startViewTransition`-API und Reacts `<ViewTransition>`-Komponente flüssige Animationen zwischen UI-Zuständen implementierst, ohne auf Drittanbieter-Bibliotheken angewiesen zu sein. Sie unterstützt Next.js (App Router) und React Canary und deckt eine breite Palette von Animationsmustern ab: Shared-Element-Morphing, Enter/Exit-Animationen, Listenneuanordnung, Suspense-Reveals und routenbasierte Übergänge mit Richtungsangabe (vorwärts/rückwärts). Der Leitfaden betont eine klare Hierarchie der zu implementierenden Muster (z. B. Shared-Element vor Suspense-Reveal) und gibt konkrete Implementierungsschritte sowie ready-to-use CSS-Rezepte aus Referenzdateien vor. Er erklärt kritische Konzepte wie den Einsatz von `default='none'`, die korrekte Verschachtelung von `<ViewTransition>`, die Verwendung von `addTransitionType` für kontextabhängige Animationen und die Integration in Next.js (einschließlich Server Components). Entwickler lernen, wann sie welche Animation einsetzen sollten (z. B. Richtungsslides für hierarchische Navigation, Fade für laterale Navigation) und wie Barrierefreiheit (reduced motion) berücksichtigt wird.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/xzedm/clipplic-landing/tree/HEAD/.agents/skills/vercel-react-view-transitions

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Vorschau

Aus dem Skill-README

React View Transitions preview
React View Transitions preview

Dokumentation

Was macht React View Transitions?

Animiere zwischen UI-Zuständen mithilfe der nativen browserbasierten document.startViewTransition. Deklariere was mit <ViewTransition>, löse wann aus mit startTransition / useDeferredValue / Suspense, steuere wie mit CSS-Klassen. Nicht unterstützte Browser überspringen Animationen elegant.

Wann animieren?

Jedes <ViewTransition> sollte eine räumliche Beziehung oder Kontinuität vermitteln. Wenn du nicht erklären kannst, was es kommuniziert, füge es nicht hinzu.

Implementiere alle anwendbaren Muster aus dieser Liste in dieser Reihenfolge:

PrioritätMusterKommuniziert
1Shared-Element (name)„Gleiche Sache, tiefer gehend“
2Suspense-Reveal„Daten geladen“
3Listenidentität (pro Element key)„Gleiche Elemente, neue Anordnung“
4Zustandsänderung (enter/exit)„Etwas erschien/verschwand“
5Routenwechsel (Layout-Ebene)„Wir gehen an einen neuen Ort“

Dies ist eine Implementierungsreihenfolge, keine „wähle eines aus“-Liste. Implementiere jedes Muster, das in die App passt. Überspringe ein Muster nur, wenn die App keinen Anwendungsfall dafür hat.

Animationsstil wählen

KontextAnimationWarum
Hierarchische Navigation (Liste → Detail)Typgesteuert nav-forward / nav-backVermittelt räumliche Tiefe
Laterale Navigation (Tab zu Tab)Bloßes <ViewTransition> (Fade) oder default='none'Keine Tiefe zu vermitteln
Suspense-Revealenter/exit-String-PropsInhalt kommt an
Revalidierung / Hintergrundaktualisierungdefault='none'Still, keine Animation nötig

Halte richtungsabhängige Slides für hierarchische Navigation (Liste → Detail) und geordnete Sequenzen (vorheriges/nächstes Foto, Karussell, paginierte Ergebnisse) reserviert. Bei geordneten Sequenzen vermittelt die Richtung die Position: „weiter“ slide von rechts, „zurück“ von links. Laterale/ungeordnete Navigation (Tab zu Tab) sollte keine Richtungsslides verwenden. Sie suggeriert fälschlicherweise räumliche Tiefe.


Verfügbarkeit

  • Next.js: Installiere nicht react@canary – der App Router bündelt bereits React canary intern. <ViewTransition> funktioniert sofort. npm ls react zeigt möglicherweise eine stabil aussehende Version an; das ist normal.
  • Ohne Next.js: Installiere react@canary react-dom@canary (ViewTransition ist nicht in stabilem React enthalten).
  • Browser-Support: Chromium 111+, Firefox 144+, Safari 18.2+. Graceful Degradation in nicht unterstützten Browsern.

Implementierungs-Workflow

Wenn du View Transitions zu einer bestehenden App hinzufügst, folge Schritt für Schritt references/implementation.md. Beginne mit dem Audit, überspringe es nicht. Kopiere die CSS-Rezepte aus references/css-recipes.md in das globale Stylesheet, schreibe kein eigenes Animations-CSS.


Kernkonzepte

Die <ViewTransition>-Komponente

import { ViewTransition } from 'react';

<ViewTransition>
  <Component />
</ViewTransition>

React weist automatisch einen eindeutigen view-transition-name zu und ruft im Hintergrund document.startViewTransition auf. Rufe startViewTransition niemals selbst auf.

Animationsauslöser

AuslöserWann er feuert
enter<ViewTransition> wird während eines Transitions erstmals eingefügt
exit<ViewTransition> wird während eines Transitions erstmals entfernt
updateDOM-Mutationen innerhalb eines <ViewTransition>. Bei verschachtelten VTs betrifft die Mutation das innerste
shareEin benanntes VT wird ausgehängt und ein anderes mit demselben name wird in derselben Transition eingehängt

Nur startTransition, useDeferredValue oder Suspense aktivieren VTs. Normales setState animiert nicht.

Kritische Platzierungsregel

<ViewTransition> aktiviert enter/exit nur, wenn es vor allen DOM-Knoten erscheint:

// Funktioniert
<ViewTransition enter="auto" exit="auto">
  <div>Inhalt</div>
</ViewTransition>

// Fehlerhaft, div umschließt das VT und unterdrückt enter/exit
<div>
  <ViewTransition enter="auto" exit="auto">
    <div>Inhalt</div>
  </ViewTransition>
</div>

Styling mit View-Transition-Klassen

Props

Werte: "auto" (Browser-Crossfade), "none" (deaktiviert), "class-name" (benutzerdefiniertes CSS) oder { [type]: value } für typspezifische Animationen.

<ViewTransition default="none" enter="slide-in" exit="slide-out" share="morph" />

Wenn default "none" ist, sind alle Auslöser ausgeschaltet, sofern nicht explizit aufgeführt.

CSS-Pseudoelemente

  • ::view-transition-old(.class): ausgehender Schnappschuss
  • ::view-transition-new(.class): eingehender Schnappschuss
  • ::view-transition-group(.class): Container
  • ::view-transition-image-pair(.class): Paar alt + neu

Siehe references/css-recipes.md für gebrauchsfertige Animationsrezepte.


Transitionstypen

Markiere Transitionen mit addTransitionType, damit VTs basierend auf dem Kontext unterschiedliche Animationen auswählen können. Rufe es mehrmals auf, um Typen zu stapeln, verschiedene VTs im Baum reagieren auf verschiedene Typen:

startTransition(() => {
  addTransitionType('nav-forward');
  addTransitionType('select-item');
  router.push('/detail/1');
});

Übergib ein Objekt, um Typen CSS-Klassen zuzuordnen. Funktioniert bei enter, exit und share:

<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' }}
  share={{ 'nav-forward': 'morph-forward', 'nav-back': 'morph-back', default: 'morph' }}
  default="none"
>
  <Page />
</ViewTransition>

enter und exit müssen nicht symmetrisch sein. Beispielsweise einblenden, aber ausblenden mit Richtung:

<ViewTransition
  enter={{ 'nav-forward': 'fade-in', 'nav-back': 'fade-in', default: 'none' }}
  exit={{ 'nav-forward': 'nav-forward', 'nav-back': 'nav-back', default: 'none' }}
  default="none"
>

TypeScript: ViewTransitionClassPerType erfordert einen default-Schlüssel im Objekt.

Extrahiere für Apps mit mehreren Seiten das typgesteuerte VT in einen wiederverwendbaren Wrapper:

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

router.back() und Zurück-Button des Browsers

router.back() und die Zurück/Vorwärts-Buttons des Browsers lösen keine View Transitions aus (popstate ist synchron, nicht kompatibel mit startViewTransition). Verwende stattdessen router.push() mit einer expliziten URL.

Typen und Suspense

Typen stehen während der Navigation zur Verfügung, aber nicht während nachfolgender Suspense-Reveals (separate Transitionen, kein Typ). Verwende Typ-Maps für Enter/Exit auf Seitenebene; verwende einfache String-Props für Suspense-Reveals.


Shared-Element-Transitionen

Derselbe name auf zwei VTs, eines wird ausgehängt, eines eingehängt, erzeugt ein Shared-Element-Morphing:

<ViewTransition name="hero-image">
  <img src="/thumb.jpg" onClick={() => startTransition(() => onSelect())} />
</ViewTransition>

// Auf der anderen Ansicht, derselbe Name
<ViewTransition name="hero-image">
  <img src="/full.jpg" />
</ViewTransition>
  • Es kann nur ein VT mit einem bestimmten name gleichzeitig eingehängt sein. Verwende eindeutige Namen (photo-${id}). Achte auf wiederverwendbare Komponenten: Wenn eine Komponente mit einem benannten VT sowohl in einem Modal/Popover als auch auf einer Seite gerendert wird, sind beide gleichzeitig aktiv und unterbrechen das Morphing. Mache den Namen entweder konditional (über eine Prop) oder verschiebe das benannte VT aus der gemeinsamen Komponente in den spezifischen Verwender.
  • share hat Vorrang vor enter/exit. Denke jeden Navigationspfad durch: Wenn kein passendes Paar entsteht (z. B. die Zielseite hat nicht denselben Namen), feuert stattdessen enter/exit. Überlege, ob das Element für diese Pfade eine Fallback-Animation benötigt.
  • Verwende niemals einen Fade-Out-Exit auf Seiten mit Shared-Morphs. Verwende stattdessen einen Richtungsslide.

Häufige Muster

Enter/Exit

{show && (
  <ViewTransition enter="fade-in" exit="fade-out"><Panel /></ViewTransition>
)}

Listenneuanordnung

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

Auslösen innerhalb von startTransition. Vermeide umschließende <div>-Elemente zwischen Liste und VT.

Zusammensetzen von Shared-Elementen und Listenidentität

Shared-Elemente und Listenidentität sind unabhängige Belange, verwechsle nicht eines mit dem anderen. Wenn ein Listenelement ein Shared-Element enthält (z. B. ein Bild, das in eine Detailansicht übergeht), verwende zwei verschachtelte <ViewTransition>-Grenzen:

{items.map(item => (
  <ViewTransition key={item.id}>                                      {/* Listenidentität */}
    <Link href={`/items/${item.id}`}>
      <ViewTransition name={`item-image-${item.id}`} share="morph">   {/* Shared-Element */}
        <Image src={item.image} />
      </ViewTransition>
      <p>{item.name}</p>
    </Link>
  </ViewTransition>
))}

Das äußere VT übernimmt die Listen-Neuordnung/Enter-Animationen. Das innere VT übernimmt das routenübergreifende Shared-Element-Morphing. Fehlt eine der beiden Ebenen, wird diese Animation stillschweigend nicht ausgeführt.

Erneute Enter-Erzwingung mit key

<ViewTransition key={searchParams.toString()} enter="slide-up" default="none">
  <ResultsGrid />
</ViewTransition>

Vorsicht: Wenn <Suspense> umschlossen wird, mountet eine Änderung des key die Grenze neu und führt zu einem erneuten Fetch.

Suspense-Fallback zu Inhalt

Einfaches Crossfade:

<ViewTransition>
  <Suspense fallback={<Skeleton />}><Content /></Suspense>
</ViewTransition>

Richtungsgesteuerter Reveal:

<Suspense fallback={<ViewTransition exit="slide-down"><Skeleton /></ViewTransition>}>
  <ViewTransition enter="slide-up" default="none"><Content /></ViewTransition>
</Suspense>

Weitere Muster findest du in references/patterns.md.


Wie mehrere VTs interagieren

Jedes VT, das den Auslöser erfüllt, feuert gleichzeitig in einem einzigen document.startViewTransition. VTs in verschiedenen Transitionen (Navigation vs. späterer Suspense-Auflösung) konkurrieren nicht.

Verwende default="none" großzügig

Ohne default="none" feuert jedes VT das Browser-Crossfade bei jeder Transition. Suspense löst auf, useDeferredValue-Updates, Hintergrundrevalidierungen. Verwende immer default="none" und aktiviere explizit nur gewünschte Auslöser.

Zwei Muster koexistieren

Muster A: Richtungsslides: Typgesteuertes VT auf jeder Seite, feuert während der Navigation. Muster B: Suspense-Reveals: Einfache String-Props, feuert beim Laden von Daten (kein Typ).

Sie koexistieren, weil sie zu unterschiedlichen Zeitpunkten feuern. default="none" auf beiden verhindert gegenseitige Beeinflussung. Paare immer enter mit exit. Platziere richtungsgesteuerte VTs in Seitenkomponenten, nicht in Layouts.

Einschränkung bei verschachtelten VTs

Wenn ein übergeordnetes VT beendet wird, feuern darin verschachtelte VTs nicht ihr eigenes enter/exit, nur das äußerste VT animiert. Staffel-Animationen pro Element während der Seitennavigation sind derzeit nicht möglich. Siehe react#36135 für einen experimentellen Opt-in-Fix.


Next.js-Integration

Für die Next.js-Einrichtung (experimental.viewTransition-Flag, transitionTypes-Prop auf next/link, App Router-Muster, Server Components) siehe references/nextjs.md.


Barrierefreiheit

Füge immer das CSS für reduzierte Bewegung aus references/css-recipes.md zu deinem globalen Stylesheet hinzu.


Referenzdateien

  • references/implementation.md: Schritt-für-Schritt-Implementierungsworkflow.
  • references/patterns.md: Muster, Animations-Timing, Events-API, Fehlerbehebung.
  • references/css-recipes.md: Gebrauchsfertige CSS-Animationsrezepte.
  • references/nextjs.md: Next.js App Router-Muster und Server Component-Details.

Vollständig kompiliertes Dokument

Für die vollständige Anleitung mit allen erweiterten Referenzdateien: AGENTS.md

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

xzedm/clipplic-landing

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.

xzedm/clipplic-landing

Material Design 3 and Android platform guidelines. Use when building Android apps with Jetpack Compose or XML layouts, implementing Material You, navigation, or accessibility. Triggers on tasks involving Android UI, Compose components, dynamic color, or Material Design compliance.

xzedm/clipplic-landing

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

xzedm/clipplic-landing

Design iOS apps following Apple's Human Interface Guidelines. Generate native components, validate designs, and ensure accessibility compliance for iPhone, iPad, and Apple Watch.

xzedm/clipplic-landing

Redesign mobile app UI to feel unmistakably Apple-like, iOS-forward, and native. Use this skill when building iOS apps, applying Apple Human Interface Guidelines, or creating native-feeling mobile interfaces with SF Pro typography, translucency, and system-like components.

xzedm/clipplic-landing

Accessibility engineering for product interfaces, from focus states and keyboard support to ARIA, forms, and screen readers. Use when building or reviewing UI components, modals, menus, forms, custom widgets, or when the user says "make this accessible" or reports keyboard or screen-reader issues. Triggers on accessibility, a11y, WCAG, aria, focus ring, focus-visible, focus trap, keyboard navigation, tab order, tabindex, screen reader, sr-only, aria-live, alt text, hit area, touch target, prefers-reduced-motion, autoplay, toast duration, skip link, semantic HTML, aria-label, form errors, disabled buttons, "not keyboard accessible".

xzedm/clipplic-landing

OKLCH color space and color usage for web projects. Convert hex/rgb/hsl to oklch, generate palettes, check contrast, handle gamut boundaries, theme with Tailwind v4, and apply color with meaning. Triggers on oklch, color conversion, palette generation, contrast ratio, gamut, display p3, design tokens, semantic color tokens, hue drift, chroma, dark mode colors, accent color, color meaning, light and dark appearance, increased contrast.

xzedm/clipplic-landing

Layout structure for web interfaces, from grouping and alignment to reading order, progressive disclosure, and adaptive breakpoints. Use when structuring a page or component, spacing or aligning controls, deciding what collapses at small sizes, handling RTL layout direction, or reviewing frontend code for layout. Triggers on layout, spacing, alignment, grouping, negative space, whitespace, visual hierarchy, reading order, progressive disclosure, breakpoints, responsive layout, container queries, safe area, full-bleed, edge-to-edge, layout margins, RTL layout, logical properties.

xzedm/clipplic-landing

Web typography from choosing fonts to spacing, wrapping and accessibility. Use when picking or pairing typefaces, configuring variable fonts or OpenType features, setting up a type scale, checking heading hierarchy, styling text in components, truncating text, styling underlines, selection, placeholders or carets, or reviewing frontend code for typography. Triggers on typography, fonts, font formats, woff2, variable fonts, font-weight, opentype, font-feature-settings, letter-spacing, line-height, type scale, heading hierarchy, heading levels, tabular numbers, text-wrap, truncation, line clamp, underlines, text-decoration, text selection, iOS input zoom, scaled input text, font smoothing, text contrast, measure, line length, text-box, smart punctuation, drop cap.

xzedm/clipplic-landing

Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, micro-interactions, enter/exit animations, choosing or reviewing icons, or any visual detail work. Triggers on UI polish, design details, "make it feel better", "feels off", stagger animations, border radius, optical alignment, image outlines, box shadows, icons, icon stroke weight, icon states, motion restraint.

xzedm/clipplic-landing

Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".

xzedm/clipplic-landing

Generate developer handoff specs from a design. Use when a design is ready for engineering and needs a spec sheet covering layout, design tokens, component props, interaction states, responsive breakpoints, edge cases, and animation details.

xzedm/clipplic-landing

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

xzedm/clipplic-landing

Extract design primitives from a public website and generate starter token files for your project.

xzedm/clipplic-landing

Use this skill alongside figma-use when the task involves translating an application page, view, or multi-section layout into Figma. Triggers: 'write to Figma', 'create in Figma from code', 'push page to Figma', 'take this app/page and build it in Figma', 'create a screen', 'build a landing page in Figma', 'update the Figma screen to match code', 'convert this modal/dialog/drawer/panel to Figma'. This is the preferred workflow skill whenever the user wants to build or update a full page, modal, dialog, drawer, sidebar, panel, or any composed multi-section view in Figma from code or a description. Discovers design system components, variables, and styles from Code Connect files, existing screens, and library search, then imports them and assembles views incrementally section-by-section using design system tokens instead of hardcoded values.

xzedm/clipplic-landing

**MANDATORY prerequisite**: you MUST invoke this skill BEFORE every `use_figma` tool call. NEVER call `use_figma` directly without loading this skill first. Skipping it causes common, hard-to-debug failures. Trigger whenever the user wants to perform a write action or a unique read action that requires JavaScript execution in the Figma file context, e.g. create/edit/delete nodes, set up variables or tokens, build components and variants, modify auto-layout or fills, bind variables to properties, or inspect file structure programmatically.

xzedm/clipplic-landing

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

xzedm/clipplic-landing

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications.

xzedm/clipplic-landing

Elite UX/UI & Advanced GSAP Motion Engineer. Enforces Python-driven true randomization for layout variance, strict AIDA page structure, wide editorial typography (bans 6-line wraps), gapless bento grids, strict GSAP ScrollTriggers (pinning, stacking, scrubbing), inline micro-images, and massive section spacing.

xzedm/clipplic-landing

Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with elements, verify state, diff before/after, take annotated screenshots, test responsive layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack)

Verwandte Skills