# Web Animations API (WAAPI) vs View Transitions API

- **Canonical URL:** https://frontend.rocks/vs/web-animations-api-vs-view-transitions-api/
- **Relation:** Contrasts With
- **Last Verified:** 2026-11-15
- **Verdict:** WAAPI animates live DOM properties on one tree, whereas View Transitions crossfade rasterized old/new snapshots.

## Comparison Matrix

| Dimension | Web Animations API (WAAPI) | View Transitions API |
| :--- | :--- | :--- |
| **Maturity** | Baseline · Widely | Baseline · Newly |
| **Domain** | Rendering Pipeline | Rendering Pipeline |
| **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. |
| **Prerequisites** | requestAnimationFrame & VSync (WAAPI replaces manual rAF loops for imperative keyframe animations.); GPU Compositor Layers and will-change (Compositor-friendly properties (transform, opacity) run off the main thread.) | Paint & Rasterization (View transitions capture rasterized GPU snapshots of old and new element states.); GPU Compositor Layers and will-change (The ::view-transition pseudo-element tree animates captured textures on the compositor.); User Preference Media Queries (Root morph transitions must respect prefers-reduced-motion: reduce to avoid vestibular discomfort.) |
| **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). |

## Web Animations API (WAAPI) — Under the Hood
A manual rAF loop is a pilot hand-flying every millisecond; WAAPI files a flight plan with the autopilot on the Compositor Thread and steps out of the cockpit.

1. **Keyframe Serialization**: When keyframes only touch [GPU Compositor Layers](/concepts/gpu-compositor-layers) properties (`transform`, `opacity`, `filter`, `clip-path`), the engine ships the timing curve to the Compositor Thread.
2. **Playback Control**: `anim.pause()`, `anim.reverse()`, `anim.playbackRate`, and `await anim.finished` synchronize with the underlying timeline without polling.
3. **Commit & Cleanup**: Avoid leaving `fill: 'forwards'` active forever; persist final values with `anim.commitStyles()` and release the animation.

```js
const anim = card.animate(
  [{ transform: 'translateY(16px)', opacity: 0 }, { transform: 'translateY(0)', opacity: 1 }],
  { duration: 220, easing: 'cubic-bezier(0.2, 0, 0, 1)', fill: 'forwards' }
);
await anim.finished;
anim.commitStyles();
anim.cancel();
```

## View Transitions API — Under the Hood
Instead of keeping two competing UI trees alive in memory during a route change, the engine takes a photograph of the outgoing room, swaps the furniture, and cross-fades the photo into reality.

1. **Snapshot Phase**: Elements with a unique `view-transition-name` are captured during [Paint & Rasterization](/concepts/paint-rasterization) as isolated textures.
2. **Mutation Phase**: Rendering pauses while the callback mutates the DOM.
3. **Pseudo-Tree Morph**: The engine injects `::view-transition-group`, `-old`, and `-new` pseudo-elements over the viewport, animating size, transform, and opacity on [GPU Compositor Layers](/concepts/gpu-compositor-layers).

```js
function navigateToCard(card, nextHtml) {
  if (!document.startViewTransition) return (main.innerHTML = nextHtml);
  card.style.viewTransitionName = 'active-card';
  const vt = document.startViewTransition(() => {
    main.innerHTML = nextHtml;
  });
  vt.finished.finally(() => { card.style.viewTransitionName = ''; });
}
```

## Interactive Labs & Dissections
- [Web Animations API (WAAPI) Lab](https://frontend.rocks/concepts/web-animations-api/#lab) ([Markdown](https://frontend.rocks/concepts/web-animations-api.md))
- [View Transitions API Lab](https://frontend.rocks/concepts/view-transitions-api/#lab) ([Markdown](https://frontend.rocks/concepts/view-transitions-api.md))

## Primary Sources
- https://drafts.csswg.org/web-animations-1/
- https://developer.mozilla.org/en-US/docs/Web/API/Web_Animations_API
- https://drafts.csswg.org/css-view-transitions-1/
- https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API
