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

> Learn how to integrate Anime.js with the Web Animations API WAAPI. Utilize Anime.js's expressive API with the browser's native Element.animate method for efficient animations.

- Repository: [Julian Garnier/anime](https://github.com/juliangarnier/anime)
- Tags: how-to-guide
- Published: 2026-03-04

---

**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`](https://github.com/juliangarnier/anime/blob/main/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`](https://github.com/juliangarnier/anime/blob/main/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`](https://github.com/juliangarnier/anime/blob/main/helpers.js) / [`targets.js`](https://github.com/juliangarnier/anime/blob/main/targets.js) / [`values.js`](https://github.com/juliangarnier/anime/blob/main/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

```javascript
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

```javascript
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:

```javascript
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`](https://github.com/juliangarnier/anime/blob/main/src/waapi/waapi.js).

### Function-Based Values

```javascript
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`](https://github.com/juliangarnier/anime/blob/main/src/waapi/waapi.js)) transforms Anime.js easing functions into CSS `linear()` timing strings.

### Custom Easing Conversion Example

```javascript
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`](https://github.com/juliangarnier/anime/blob/main/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

```javascript
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`](https://github.com/juliangarnier/anime/blob/main/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`](https://github.com/juliangarnier/anime/blob/main/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.