|$ curl https://forge-ai.dev/api/markdown?path=docs/web-platform/web-animations
$cat docs/web-animations-api.md
updated Recently·25 min read·published
Web Animations API
Introduction
The Web Animations API provides a JavaScript interface for CSS animations and transitions, giving you precise control over timing, playback, and keyframes without the limitations of CSS-only approaches. It combines the capabilities of CSS animations and JavaScript-driven animation in a single unified model.
Element.animate()
element-animate.ts
TypeScript
| 1 | // Basic animation |
| 2 | const box = document.querySelector(".box")!; |
| 3 | |
| 4 | const animation = box.animate( |
| 5 | [ |
| 6 | { transform: "translateX(0)", opacity: 0 }, |
| 7 | { transform: "translateX(100px)", opacity: 1 }, |
| 8 | ], |
| 9 | { |
| 10 | duration: 500, |
| 11 | easing: "ease-out", |
| 12 | fill: "forwards", // Keep final state |
| 13 | } |
| 14 | ); |
| 15 | |
| 16 | // Multiple keyframes with offsets |
| 17 | const fadeSlide = box.animate( |
| 18 | [ |
| 19 | { opacity: 0, transform: "translateY(20px)", offset: 0 }, |
| 20 | { opacity: 0.5, transform: "translateY(10px)", offset: 0.5 }, |
| 21 | { opacity: 1, transform: "translateY(0)", offset: 1 }, |
| 22 | ], |
| 23 | { duration: 300, easing: "cubic-bezier(0.4, 0, 0.2, 1)" } |
| 24 | ); |
| 25 | |
| 26 | // Staggered animations on multiple elements |
| 27 | const items = document.querySelectorAll(".list-item"); |
| 28 | items.forEach((item, i) => { |
| 29 | item.animate( |
| 30 | [{ opacity: 0, transform: "translateY(20px)" }, { opacity: 1, transform: "translateY(0)" }], |
| 31 | { duration: 300, delay: i * 50, fill: "forwards" } |
| 32 | ); |
| 33 | }); |
Playback Control
playback.ts
TypeScript
| 1 | const animation = box.animate( |
| 2 | [{ transform: "rotate(0deg)" }, { transform: "rotate(360deg)" }], |
| 3 | { duration: 2000, iterations: Infinity } |
| 4 | ); |
| 5 | |
| 6 | // Playback controls |
| 7 | animation.pause(); |
| 8 | animation.play(); |
| 9 | animation.reverse(); |
| 10 | animation.cancel(); |
| 11 | animation.finish(); // Jump to end |
| 12 | |
| 13 | // Seek to specific point |
| 14 | animation.currentTime = 500; // 500ms into the animation |
| 15 | |
| 16 | // Playback rate |
| 17 | animation.playbackRate = 2; // 2x speed |
| 18 | animation.playbackRate = 0.5; // Half speed |
| 19 | animation.playbackRate = -1; // Reverse playback |
| 20 | |
| 21 | // Event listeners |
| 22 | animation.onfinish = () => console.log("Animation complete"); |
| 23 | animation.oncancel = () => console.log("Animation cancelled"); |
| 24 | animation.onpause = () => console.log("Animation paused"); |
| 25 | animation.onplay = () => console.log("Animation started"); |
| 26 | |
| 27 | // Promise-based completion |
| 28 | await animation.finished; |
| 29 | console.log("Done!"); |
ℹ
info
Use fill: "forwards"to keep the animation's final state visible after completion. Without it, the element snaps back to its original state.
CSS vs JS Animations
| Aspect | CSS Animations | Web Animations API |
|---|---|---|
| Performance | Compositor-accelerated (transform, opacity) | Same — uses same rendering pipeline |
| Control | Limited (play/pause class toggle) | Full (currentTime, playbackRate, events) |
| Dynamic values | Requires CSS variables hacks | Native JavaScript variables |
| Reusability | Define once, apply anywhere | Create per-element or share KeyframeEffect |
✓
best practice
Use CSS animations for simple hover states and transitions. Use the Web Animations API for dynamic, interactive, or programmatically controlled animations. Both use the same compositor pipeline — neither is inherently faster.
$Blueprint — Engineering Documentation·Section ID: WP-WA-01·Revision: 1.0