Rendering PipelineBaseline · Widely

Web Animations API (WAAPI)

Mental Model

The Web Animations API (WAAPI) lets JavaScript drive the exact same C++ animation engine that powers CSS @keyframes. Calling element.animate() with compositor properties offloads interpolation to the GPU thread while giving JS a Promise-based Animation controller.

Interactive Simulator

rAF Transform Loop vs element.animate()

Compare main-thread rAF animation against compositor-offloaded WAAPI.

Lines of Code
Before
7
After
5
Reflows / Browser Cost
Before
0 (stalls if JS blocks)
After
0 (Compositor Thread)
BeforeManual rAF Interpolation
function slide(start) {
  requestAnimationFrame((now) => {
    const p = Math.min(1, (now - start) / 300);
    el.style.transform = `translateX(${p * 120}px)`;
    if (p < 1) slide(start);
  });
}
Lines: 7Reflows: 0 (stalls if JS blocks)Dependencies: Main-thread rAF loop

Freezes whenever a 50ms JS task blocks the main thread.

After (Native)Native WAAPI (Compositor)
const anim = el.animate(
  [{ transform: 'translateX(0)' }, { transform: 'translateX(120px)' }],
  { duration: 300, easing: 'ease-out' }
);
await anim.finished;
Lines: 5Reflows: 0 (Compositor Thread)Dependencies: 0 main-thread ticks

Runs smoothly on the GPU Compositor Thread even during JS work.

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 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();

Problem Genealogy

  • 2012–2016: Developers either hacked CSS class toggles with fragile transitionend listeners or wrote heavy JS tweening libraries.
  • 2020+: All major engines converged on WAAPI Level 1, unifying CSS animations, transitions, and JS-created animations under one timeline model.

Production Pitfalls

Production Pitfall
  • 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.
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.

Connections & Logical Next Steps

Mechanical Comparisons