View Transitions API

When to use this

• You are swapping DOM content (route change in a SPA, tab switch, list reorder) and want an automatic cross-fade or a shared-element "morph" (an image growing from a thumbnail to a detail view) without manually animating both states.
• You run a traditional multi-page site (MPA) and want smooth transitions between full navigations without adopting a SPA framework, using the newer cross-document view transitions.
• You need per-element transition identity (view-transition-name) so specific elements morph into their counterpart on the next page/state while everything else cross-fades.
• Do NOT use this for scroll-linked or continuously-scrubbed animation; view transitions are one-shot, triggered-by-a-state-change transitions, not scroll-position-driven. Use css-scroll-driven-animations or sticky-pinning-sequences for anything tied to scroll position instead.

Mental model

When you call document.startViewTransition(callback), the browser does something conceptually simple but implemented at the compositor level: it takes a screenshot of the current DOM state (the "old" state), runs your callback synchronously to mutate the DOM into its "new" state, then takes a screenshot-equivalent capture of that new state. It builds a pseudo-element tree overlaying the page: ::view-transition-group(name) containing ::view-transition-image-pair(name) containing ::view-transition-old(name) and ::view-transition-new(name). By default, the whole page is treated as one group named root, cross-fading old-root into new-root.

Any element you tag with view-transition-name: some-name (unique per name, at most one element per name at a time) gets pulled out into its own group, captured separately in both states, and the browser automatically animates a smooth transform+size+cross-fade between the old and new bounding boxes of that named element. This is what produces the "shared element" morph effect: same view-transition-name on a thumbnail before and the full image after, and the browser interpolates position/size/aspect-ratio between them for you, no manual FLIP math required.

Cross-document view transitions (MPA) work almost identically but are opt-in per navigation: both the outgoing and incoming pages need @view-transition { navigation: auto; } in CSS, and the browser handles capturing old-page/new-page across the actual page unload/load boundary — impossible before this API since navigations used to hard-cut.

Critically, startViewTransition is synchronous-DOM-mutation-based: the callback (or the returned promise-driven update) must finish its DOM changes before the browser can capture the "new" state; async data fetching should happen before calling startViewTransition, not inside it.