Web Animations API (WAAPI) vs View Transitions API
WAAPI animates live DOM properties on one tree, whereas View Transitions crossfade rasterized old/new snapshots.
Structured Comparison Matrix
| Dimension | Web Animations API (WAAPI) | View Transitions API |
|---|---|---|
| Mental Model | element.animate() exposes the browser’s native compositor animation engine to JavaScript with pause, reverse, and finished promises. | document.startViewTransition() snapshots old and new DOM states as rasterized textures and cross-fades or morphs them automatically. |
| Maturity & Domain | Baseline · Widely · Rendering Pipeline Chrome 36+ · Firefox 48+ · Safari 13.1+ | Baseline · Newly · Rendering Pipeline Chrome 111+ · Firefox 144+ · Safari 18+ |
| Prerequisites | ||
| When Not to Use | When not to use WAAPI: For simple state transitions (hover, focus, open/close), plain CSS transition is simpler and requires zero JavaScript; for route or DOM-swap morphs, use the View Transitions API. | When not to use View Transitions: Avoid wrapping high-frequency micro-interactions (hover states, typing) in startViewTransition(); reserve it for route or panel transitions, and gate motion behind User-Preference Media Queries (prefers-reduced-motion). |
Engine Mechanics & Trade-Offs
Keyframes targeting transform/opacity/filter serialize to the Compositor Thread; main-thread JS stalls cannot freeze them.
Key Pitfalls: fill: 'forwards' retention: Completed filling animations stay in memory and override inline styles until explicitly canceled. Main-thread fallback: Adding height or margin to a WAAPI keyframe silently demotes the entire animation to the main thread.
Engine pauses rendering briefly to capture old textures, executes DOM mutation, then animates ::view-transition-old/new pairs.
Key Pitfalls: Duplicate view-transition-name: Two visible elements with the same view-transition-name abort the entire transition. Async network calls inside the callback: Awaiting fetch() inside startViewTransition() freezes user input until the network responds.