WAAPI (Web Animations API)

A lightweight wrapper around the Web Animations API that makes it easier to animate DOM elements with staggered values, per-element options, and helper utilities.

Installation

npm install @static-bolt/waapi

API

animate(target, options): Animation[]

Animate one or more elements with shared or staggered options.

• target: Element | Element[] | string
  CSS selector, element, or array of elements.
• options: AnimateOptions
  Animation settings (duration, easing, cssProps, etc.).

Returns an array of Animation objects.

animateSingle(target, options): Animation

Convenience wrapper for animating a single element.
Accepts the same options as animate, but only returns one animation.

stagger(value, options?): IndexedTransform

Helper for creating staggered values. Returns a function that maps (index, length) → value.

• value: number to increment/distribute
• options: StaggerFnOptions

Example:

stagger(100); // 0, 100, 200, 300, ...
stagger(100, { distribute: true }); // 0, 25, 50, 75, 100
stagger(10, { reversed: true }); // reversed order

Types

AnimateOptions

Main configuration object passed to animate.

Key properties:

• cssProps: object of CSS properties to animate. Supports single values, arrays (multi-step keyframes), and functions (i, ln) => value for per-element control.
• id: string identifier for the animation
• delay: ms before start
• duration: ms per iteration
• easing: easing function string
• iterations: repeat count (number or Infinity)
• loop: shorthand for infinite loop
• autoplay: start automatically
• commitStyles: apply final styles to element
• persist: keep animation from being removed automatically
• onfinish, oncancel, onremove: event callbacks

Usage Examples

1. Animate a single element

import { animateSingle } from "@static-bolt/waapi";

animateSingle("#box", {
  duration: 1000,
  easing: "ease-in-out",
  cssProps: {
    transform: ["translateX(0px)", "translateX(200px)"],
    opacity: [1, 0.2],
  },
  autoplay: true,
  onfinish: () => console.log("Animation finished!"),
});

2. Animate multiple elements with stagger

import { animate, stagger } from "@static-bolt/waapi";

animate(".item", {
  duration: 800,
  easing: "ease-out",
  cssProps: {
    transform: ["scale(0.5)", "scale(1)"],
  },
  delay: stagger(100),
  autoplay: true,
});

3. Looping spinner

animateSingle("#spinner", {
  duration: 1000,
  easing: "linear",
  loop: true,
  cssProps: {
    transform: ["rotate(0deg)", "rotate(360deg)"],
  },
  autoplay: true,
});

4. Multi-step keyframes with color

animate("#box", {
  duration: 2000,
  easing: "ease-in-out",
  cssProps: {
    transform: ["translateX(0px)", "translateX(200px)", "translateY(100px)", "translateX(0px)"],
    background: ["red", "orange", "yellow", "green"],
  },
  autoplay: true,
});

5. Using stagger template

animate(".bar", {
  duration: 500,
  easing: "ease-out",
  cssProps: {
    transform: ["scaleY(0)", "scaleY(1)"],
    height: stagger(10, { template: "$px" }),
  },
  autoplay: true,
});

License

@static-bolt/waapi library is licensed under The MIT License.