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ät | Muster | Kommuniziert |
|---|---|---|
| 1 | Shared-Element (name) | „Gleiche Sache, tiefer gehend“ |
| 2 | Suspense-Reveal | „Daten geladen“ |
| 3 | Listenidentität (pro Element key) | „Gleiche Elemente, neue Anordnung“ |
| 4 | Zustandsänderung (enter/exit) | „Etwas erschien/verschwand“ |
| 5 | Routenwechsel (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
| Kontext | Animation | Warum |
|---|---|---|
| Hierarchische Navigation (Liste → Detail) | Typgesteuert nav-forward / nav-back | Vermittelt räumliche Tiefe |
| Laterale Navigation (Tab zu Tab) | Bloßes <ViewTransition> (Fade) oder default='none' | Keine Tiefe zu vermitteln |
| Suspense-Reveal | enter/exit-String-Props | Inhalt kommt an |
| Revalidierung / Hintergrundaktualisierung | default='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 reactzeigt möglicherweise eine stabil aussehende Version an; das ist normal. - Ohne Next.js: Installiere
react@canary react-dom@canary(ViewTransitionist 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öser | Wann er feuert |
|---|---|
| enter | <ViewTransition> wird während eines Transitions erstmals eingefügt |
| exit | <ViewTransition> wird während eines Transitions erstmals entfernt |
| update | DOM-Mutationen innerhalb eines <ViewTransition>. Bei verschachtelten VTs betrifft die Mutation das innerste |
| share | Ein 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
namegleichzeitig 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. sharehat Vorrang vorenter/exit. Denke jeden Navigationspfad durch: Wenn kein passendes Paar entsteht (z. B. die Zielseite hat nicht denselben Namen), feuert stattdessenenter/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
