How to Integrate Anime.js with the Web Animations API (WAAPI)

Anime.js integrates with the Web Animations API through a dedicated WAAPI engine that drives animations via the browser's native Element.animate() method while preserving the library's expressive API.

The juliangarnier/anime repository ships a complete WAAPI integration layer located in the src/waapi folder. This engine allows you to leverage native browser performance for CSS animations without sacrificing Anime.js features like stagger, function-based values, or timeline synchronization.

Understanding the WAAPI Engine Architecture

The WAAPI integration is modularized across several key files in the src/waapi directory:

Core Components in src/waapi

• waapi.js — Exposes waapi.animate() and waapi.convertEase(). Contains the WAAPIAnimation class that handles parameter parsing, CSS custom property registration for transforms, and coordination of multiple target elements.
• composition.js — Provides low-level helpers addWAAPIAnimation() and removeWAAPIAnimation() that manage native Animation objects, maintain a linked list of active instances, and handle cleanup on finish or cancel.
• helpers.js / targets.js / values.js — Utility modules used by the WAAPI engine for target resolution (registerTargets), function evaluation (getFunctionValue), and value merging (setValue).

How to Use waapi.animate() for Native Performance

The waapi.animate() function mirrors the standard Anime.js API but routes animations through the browser's native WAAPI implementation.

Basic Single Target Animation

import { waapi } from 'animejs';

// Animate #box 300px to the right over 800ms
waapi.animate('#box', {
  translateX: 300,
  duration: 800,
  easing: 'easeOutQuad',
  autoplay: true,
});

Staggered Animations with Multiple Elements

import { waapi, stagger } from 'animejs';

waapi.animate('.dot', {
  translateX: 200,
  duration: 500,
  delay: stagger(100, { from: 'center' }),
  easing: 'easeOutCubic',
});

Individual Transform Axes via CSS Custom Properties

The WAAPI engine automatically registers CSS custom properties for individual transform axes:

import { waapi } from 'animejs';

waapi.animate('#shape', {
  x: 120,            // Maps to --translateX
  y: 80,             // Maps to --translateY
  rotate: 45,        // Maps to --rotate
  scale: 1.5,        // Maps to --scale
  duration: 1000,
  easing: 'linear',
});

Under the hood, the engine calls CSS.registerProperty() for each axis (with fallback for unsupported browsers) and constructs composite transform strings. This logic resides in the WAAPIAnimation class within src/waapi/waapi.js.

Function-Based Values

import { waapi, stagger } from 'animejs';

waapi.animate('.item', {
  translateX: (el, i) => `${i * 50}px`,
  opacity: (el, i) => 1 - i * 0.2,
  duration: 600,
  delay: stagger(80),
});

Converting Custom Easing for WAAPI Compatibility

WAAPI requires CSS-compatible easing strings. The waapi.convertEase() function (exposed from src/waapi/waapi.js) transforms Anime.js easing functions into CSS linear() timing strings.

Custom Easing Conversion Example

import { waapi } from 'animejs';

// Custom easing: fast start, slow end
const myEase = t => t === 0 ? 0 : Math.pow(t, 0.3);

waapi.animate('#ball', {
  translateY: 200,
  duration: 1200,
  easing: myEase,  // Automatically converted via easingToLinear
});

The conversion occurs in easingToLinear() (lines 85-89 of waapi.js), which samples the function 100 times by default to generate the linear(...) string. Results are cached in WAAPIEasesLookups to prevent recomputation.

Synchronizing WAAPI Animations with Anime.js Timelines

The WAAPIAnimation class implements the same control interface as standard Anime.js animations, enabling seamless timeline integration.

Timeline Synchronization Example

import { waapi, createTimeline } from 'animejs';

const animA = waapi.animate('#a', {
  opacity: [0, 1],
  duration: 500,
  easing: 'linear',
});

const animB = waapi.animate('#b', {
  translateX: 300,
  duration: 500,
  easing: 'easeOutQuad',
});

const tl = createTimeline({ autoplay: false, loop: true })
  .sync(animA)        // Starts at t = 0
  .sync(animB, 250);  // Starts 250ms after animA

tl.play(); // Both WAAPI animations run in lock-step

The timeline calls seek(), play(), and pause() on the WAAPIAnimation instances, which proxy these commands to the underlying native animations via src/waapi/composition.js.

Summary

• Anime.js provides a dedicated WAAPI engine in src/waapi that routes animations through the browser's native Element.animate() method.
• Use waapi.animate() to create high-performance animations with the same API as standard Anime.js, supporting stagger, function-based values, and individual transform axes.
• Custom easing functions are automatically converted to CSS linear() strings via waapi.convertEase() and cached for performance.
• Timeline integration works seamlessly because WAAPIAnimation implements the same control interface (play, pause, seek) as regular Anime.js animations.
• CSS custom properties for individual transforms (x, y, rotate, scale) are automatically registered when using the WAAPI engine.

Frequently Asked Questions

What is the Web Animations API (WAAPI)?

The Web Animations API is a native browser API that provides a JavaScript interface for creating and controlling CSS animations. It offers better performance than JavaScript-based animation loops because it runs on the browser's compositor thread. Anime.js's WAAPI engine leverages this API while maintaining the library's developer-friendly syntax.

How does Anime.js convert custom easing functions for WAAPI?

When you pass a custom easing function to waapi.animate(), the engine samples the function 100 times across the animation duration to generate a CSS linear() timing string. This conversion happens in the easingToLinear function within src/waapi/waapi.js. The results are cached in WAAPIEasesLookups to avoid recomputing the same easing function multiple times.

Can I mix WAAPI and standard Anime.js animations in the same timeline?

Yes. The WAAPIAnimation class implements the same control interface as standard Anime.js animations (play, pause, seek, progress, etc.). When you call createTimeline().sync(waapiAnimation), the timeline treats it identically to a standard animation. The WAAPI engine updates parent.duration automatically when child animations are added, ensuring timelines calculate total duration correctly regardless of the underlying engine.

Does the WAAPI engine support all Anime.js features?

The WAAPI engine supports most core features including stagger, function-based values, individual transform axes (x, y, rotate, scale), and custom easing. However, because WAAPI is a CSS-based API, it cannot animate JavaScript objects or canvas contexts—those require the standard Anime.js engine. Additionally, some advanced features like specific SVG path morphing may have limited support in the WAAPI implementation compared to the full JavaScript engine.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}