Web Animations

Animating elements with JavaScript — the Web Animations API, requestAnimationFrame, CSS transitions from JS, and GSAP.

What it is, in plain English: The Web Animations API (WAAPI) gives JavaScript direct control over CSS animations. You can create, pause, reverse, seek, and speed up animations programmatically. element.animate() is the key method — it takes keyframes and timing options and returns an Animation object. For complex animations, requestAnimationFrame gives you frame-by-frame control.

Where this bites you

transitionend fires once for each property that transitions. Animate transform and opacity together and the listener runs twice. Cleanup code (removing the element, starting the next step, counting completions) runs twice too. Calling remove() twice happens to be harmless, but most follow-up actions aren't.

// <div class="toast">Saved <button class="close">×</button></div>
const toast = document.querySelector(".toast");
let cleanups = 0;

toast.querySelector(".close").addEventListener("click", () => {
  toast.style.transition = "transform 0.3s ease, opacity 0.3s ease";
  toast.style.transform  = "translateX(200px)";
  toast.style.opacity    = "0";
});

toast.addEventListener("transitionend", (event) => {
  cleanups++;
  console.log("transitionend:", event.propertyName, "| cleanup runs:", cleanups);
  toast.remove();
});
// transitionend: opacity | cleanup runs: 1
// transitionend: transform | cleanup runs: 2

Animating elements with JavaScript

element.animate() — the Web Animations API

const element = document.querySelector(".box");

// animate(keyframes, options):
const animation = element.animate(
  [
    { transform: "scale(1)",   opacity: 1 },   // start
    { transform: "scale(1.5)", opacity: 0.5 }, // middle (optional)
    { transform: "scale(1)",   opacity: 1 },   // end
  ],
  {
    duration:   600,     // milliseconds
    easing:     "ease",  // "linear", "ease", "ease-in", "ease-out", "ease-in-out"
    delay:      200,     // delay before starting
    iterations: 1,       // 1 = once, Infinity = loop
    fill:       "forwards",  // "none", "forwards" (keep end state), "backwards", "both"
  }
);

// Control playback:
animation.pause();
animation.play();
animation.reverse();
animation.cancel();
animation.finish();  // jump to end

// Events:
animation.addEventListener("finish",  () => console.log("Done!"));
animation.addEventListener("cancel",  () => console.log("Cancelled"));

// Return value check:
const anims = element.getAnimations();  // all running animations on this element

CSS transitions from JavaScript

// Apply a CSS transition, then change the property:
element.style.transition = "transform 0.3s ease, opacity 0.3s ease";
element.style.transform  = "translateX(200px)";
element.style.opacity    = "0";

// Listen for transition end:
element.addEventListener("transitionend", (event) => {
  console.log("Transition finished:", event.propertyName);
  element.remove();
});

The example above logs event.propertyName for exactly this reason. When several properties transition together, pick one to react to and ignore the others. ({ once: true } isn't a reliable alternative: it reacts to whichever property finishes first, so it can fire before the others are done when the durations differ.)

const toast = document.querySelector(".toast");
let cleanups = 0;

toast.querySelector(".close").addEventListener("click", () => {
  toast.style.transition = "transform 0.3s ease, opacity 0.3s ease";
  toast.style.transform  = "translateX(200px)";
  toast.style.opacity    = "0";
});

toast.addEventListener("transitionend", (event) => {
  if (event.propertyName !== "opacity") return;   // react to ONE property only
  cleanups++;
  console.log("transitionend:", event.propertyName, "| cleanup runs:", cleanups);
  toast.remove();
});
// transitionend: opacity | cleanup runs: 1

requestAnimationFrame — frame-by-frame control

// Use for game loops, physics, anything that updates every frame:
let x = 0;

function update(timestamp) {
  x = (x + 1) % window.innerWidth;
  element.style.transform = `translateX(${x}px)`;
  requestAnimationFrame(update);  // schedule next frame
}

const frameId = requestAnimationFrame(update);

// Cancel the animation:
// cancelAnimationFrame(frameId);

Try It Yourself

// Web Animations API — animate() method
// Creates and runs an animation on any element

const box = document.createElement("div");
box.style.cssText = "width:80px;height:80px;background:#e94560;border-radius:8px;margin:20px";
document.body.appendChild(box);

// Basic animation: slide and fade in
const animation = box.animate(
  [
    { transform: "translateX(0px)",   opacity: 1 },    // from
    { transform: "translateX(200px)", opacity: 0.5 },  // to
  ],
  {
    duration:   1000,        // 1 second
    easing:     "ease-in-out",
    iterations: Infinity,    // loop forever
    direction:  "alternate", // ping-pong
  }
);

// Control the animation:
console.log("Animation playing:", animation.playState);

// After 2 seconds, pause it:
setTimeout(() => {
  animation.pause();
  console.log("Paused. currentTime:", animation.currentTime?.toFixed(0), "ms");
}, 2000);

// After 4 seconds, reverse it:
setTimeout(() => {
  animation.playbackRate = -1;
  animation.play();
  console.log("Reversed!");
}, 4000);

// requestAnimationFrame — manual frame control
let angle = 0;
const circle = document.createElement("div");
circle.style.cssText = "width:40px;height:40px;background:#4ecca3;border-radius:50%;position:absolute;top:120px;left:20px";
document.body.appendChild(circle);

console.log("Two animations running simultaneously.");

Sequencing, timelines, and spring physics

Sequencing animations

// Chain animations using Promises (.finished):
async function sequence(elements) {
  for (const el of elements) {
    await el.animate(
      [{ opacity: 0, transform: "translateY(20px)" },
       { opacity: 1, transform: "translateY(0)" }],
      { duration: 300, fill: "forwards" }
    ).finished;  // wait for this one to finish
    // then start the next
  }
}

// Or run in parallel with Promise.all:
async function parallel(elements) {
  await Promise.all(elements.map(el =>
    el.animate([{opacity:0},{opacity:1}], {duration:500}).finished
  ));
  console.log("All finished!");
}

Spring physics with requestAnimationFrame

// Simple spring: position follows a target with spring force
class Spring {
  constructor({ stiffness = 0.1, damping = 0.8 } = {}) {
    this.stiffness = stiffness;
    this.damping   = damping;
    this.velocity  = 0;
    this.current   = 0;
    this.target    = 0;
  }

  update() {
    const force    = (this.target - this.current) * this.stiffness;
    this.velocity  = (this.velocity + force) * this.damping;
    this.current  += this.velocity;
    return this.current;
  }
}

const spring = new Spring({ stiffness: 0.08, damping: 0.75 });
spring.target = 300;  // set target position

function animateSpring() {
  const x = spring.update();
  element.style.transform = `translateX(${x}px)`;
  requestAnimationFrame(animateSpring);
}

WAAPI spec and GSAP

// GSAP — the industry standard for complex animations:
// npm install gsap
import gsap from "gsap";

// Timeline — sequence with precise control:
const tl = gsap.timeline({ defaults: { duration: 0.5, ease: "power2.out" } });

tl.from(".hero-title",  { y: -50, opacity: 0 })
  .from(".hero-sub",    { y: -30, opacity: 0 }, "-=0.3")  // overlap by 0.3s
  .from(".hero-button", { scale: 0, opacity: 0 }, "-=0.2")
  .to(".bg",            { backgroundColor: "#e94560" }, "<");  // at same time as prev

// ScrollTrigger (GSAP plugin) — animate on scroll:
// gsap.registerPlugin(ScrollTrigger);
// gsap.from(".section", { y: 100, opacity: 0,
//   scrollTrigger: { trigger: ".section", start: "top 80%", end: "bottom 20%", scrub: true }
// });

WAAPI spec (W3C Web Animations)

The Web Animations model defines an Animation object with a timeline (typically DocumentTimeline whose currentTime = document.timeline.currentTime), an effect (KeyframeEffect), and internal playback state machine (idle → running → paused → finished). The composite option (replace/add/accumulate) controls how multiple animations on the same property combine. The spec also defines the GroupEffect (not yet widely implemented) for declarative sequencing.

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.