Web Animations API (WAAPI)
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.
rAF Transform Loop vs element.animate()
Compare main-thread rAF animation against compositor-offloaded WAAPI.
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);
});
}Freezes whenever a 50ms JS task blocks the main thread.
const anim = el.animate(
[{ transform: 'translateX(0)' }, { transform: 'translateX(120px)' }],
{ duration: 300, easing: 'ease-out' }
);
await anim.finished;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.
- 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. - Playback Control:
anim.pause(),anim.reverse(),anim.playbackRate, andawait anim.finishedsynchronize with the underlying timeline without polling. - Commit & Cleanup: Avoid leaving
fill: 'forwards'active forever; persist final values withanim.commitStyles()and release the animation.
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
transitionendlisteners 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
fill: 'forwards'retention: Completed filling animations stay in memory and override inline styles until explicitly canceled.- Main-thread fallback: Adding
heightormarginto a WAAPI keyframe silently demotes the entire animation to the main thread.
- When not to use WAAPI: For simple state transitions (hover, focus, open/close), plain CSS
transitionis simpler and requires zero JavaScript; for route or DOM-swap morphs, use the View Transitions API.
Connections & Logical Next Steps
Scroll-driven timelines plug into the same Web Animations timing model.
WAAPI replaces manual rAF loops for imperative keyframe animations.
Compositor-friendly properties (transform, opacity) run off the main thread.
WAAPI animates live DOM properties on one tree, whereas View Transitions crossfade rasterized old/new snapshots.