---name: anime-jsdescription: Expert guidelines for building performant animations with Anime.js animation library---

Anime.js Animation Guidelines

You are an expert in Anime.js, JavaScript, and web animation performance. Follow these guidelines when creating animations.

Core Principles

Installation and Import

npm install animejs

// Full import
import anime from "animejs";

// Modular import for smaller bundle size
import { animate, timeline, stagger } from "animejs";

Basic Animation

anime({
  targets: ".element",
  translateX: 250,
  rotate: "1turn",
  duration: 800,
  easing: "easeInOutQuad"
});

Performance Optimization

Frame Rate Control

// Adjust global frame rate for lower-end devices
anime.suspendWhenDocumentHidden = true;

// Control FPS for specific animations
anime({
  targets: ".element",
  translateX: 250,
  update: function(anim) {
    // Custom frame rate limiting if needed
  }
});

Use Transforms Over Layout Properties

// Good - uses GPU-accelerated transforms
anime({
  targets: ".element",
  translateX: 100,  // Good
  translateY: 50,   // Good
  scale: 1.2,       // Good
  rotate: 45,       // Good
  opacity: 0.5      // Good
});

// Avoid - causes layout recalculation
anime({
  targets: ".element",
  left: 100,        // Avoid
  top: 50,          // Avoid
  width: 200,       // Avoid
  height: 150       // Avoid
});

Use Animatable for High-Frequency Updates

import { Animatable } from "animejs";

// Optimized for continuous updates (mouse tracking, etc.)
const animatable = new Animatable(".cursor", {
  x: 0,
  y: 0
});

document.addEventListener("mousemove", (e) => {
  animatable.x = e.clientX;
  animatable.y = e.clientY;
});

Timeline Animations

Basic Timeline

const tl = anime.timeline({
  easing: "easeOutExpo",
  duration: 750
});

tl.add({
  targets: ".header",
  translateY: [-50, 0],
  opacity: [0, 1]
})
.add({
  targets: ".content",
  translateY: [30, 0],
  opacity: [0, 1]
}, "-=500") // Overlap by 500ms
.add({
  targets: ".footer",
  translateY: [30, 0],
  opacity: [0, 1]
}, "-=500");

Timeline Controls

const tl = anime.timeline({
  autoplay: false
});

// Control methods
tl.play();
tl.pause();
tl.restart();
tl.reverse();
tl.seek(1000); // Go to 1 second

Stagger Animations

Basic Stagger

anime({
  targets: ".grid-item",
  translateY: [50, 0],
  opacity: [0, 1],
  delay: anime.stagger(100) // 100ms delay between each
});

Advanced Stagger Options

// Stagger from center
anime({
  targets: ".grid-item",
  scale: [0, 1],
  delay: anime.stagger(100, { from: "center" })
});

// Grid stagger
anime({
  targets: ".grid-item",
  scale: [0, 1],
  delay: anime.stagger(50, {
    grid: [14, 5],
    from: "center"
  })
});

// Stagger with easing
anime({
  targets: ".item",
  translateX: 250,
  delay: anime.stagger(100, { easing: "easeOutQuad" })
});

Easing Functions

Built-in Easings

// Common easings
anime({
  targets: ".element",
  translateX: 250,
  easing: "easeOutExpo"     // Fast start, slow end
  // easing: "easeInOutQuad" // Smooth both ends
  // easing: "easeOutElastic(1, .5)" // Bouncy
  // easing: "easeOutBounce" // Bounce effect
  // easing: "spring(1, 80, 10, 0)" // Physics-based
});

Custom Easing

anime({
  targets: ".element",
  translateX: 250,
  easing: "cubicBezier(0.25, 0.1, 0.25, 1)"
});

SVG Animation

Path Animation

const path = anime.path(".motion-path");

anime({
  targets: ".element",
  translateX: path("x"),
  translateY: path("y"),
  rotate: path("angle"),
  easing: "linear",
  duration: 2000,
  loop: true
});

Line Drawing

anime({
  targets: "path",
  strokeDashoffset: [anime.setDashoffset, 0],
  easing: "easeInOutSine",
  duration: 1500,
  delay: anime.stagger(250)
});

Morphing

anime({
  targets: "path",
  d: [
    { value: "M10 10 L90 10 L90 90 L10 90 Z" },
    { value: "M10 50 Q50 10 90 50 Q50 90 10 50 Z" }
  ],
  easing: "easeInOutQuad",
  duration: 1000,
  loop: true,
  direction: "alternate"
});

Function-Based Values

Dynamic Values

anime({
  targets: ".element",
  translateX: function(el, i) {
    return i * 100; // Each element moves further
  },
  rotate: function(el, i, total) {
    return (360 / total) * i; // Distribute rotation
  },
  delay: function(el, i) {
    return i * 50;
  }
});

Callbacks and Events

Animation Events

anime({
  targets: ".element",
  translateX: 250,
  begin: function(anim) {
    console.log("Animation started");
  },
  update: function(anim) {
    console.log(Math.round(anim.progress) + "%");
  },
  complete: function(anim) {
    console.log("Animation completed");
  }
});

Looping

anime({
  targets: ".element",
  translateX: 250,
  direction: "alternate",
  loop: true,
  loopComplete: function(anim) {
    console.log("Loop completed");
  }
});

React Integration

Basic React Usage

import { useEffect, useRef } from "react";
import anime from "animejs";

function AnimatedComponent() {
  const elementRef = useRef(null);

  useEffect(() => {
    const animation = anime({
      targets: elementRef.current,
      translateX: 250,
      duration: 800
    });

    return () => {
      animation.pause(); // Cleanup
    };
  }, []);

  return <div ref={elementRef}>Animated</div>;
}

With useCallback for Controls

function ControlledAnimation() {
  const elementRef = useRef(null);
  const animationRef = useRef(null);

  const playAnimation = useCallback(() => {
    animationRef.current = anime({
      targets: elementRef.current,
      translateX: [0, 250],
      duration: 800
    });
  }, []);

  useEffect(() => {
    return () => {
      animationRef.current?.pause();
    };
  }, []);

  return (
    <>
      <div ref={elementRef}>Animated</div>
      <button onClick={playAnimation}>Play</button>
    </>
  );
}

Web Animations API Bridge

Using WAAPI for Native Performance

import { wapiAnimate } from "animejs";

// Uses browser's native Web Animations API
wapiAnimate(".element", {
  translateX: 250,
  duration: 800
});

Accessibility

Respect Reduced Motion

const prefersReducedMotion = window.matchMedia(
  "(prefers-reduced-motion: reduce)"
).matches;

anime({
  targets: ".element",
  translateX: 250,
  duration: prefersReducedMotion ? 0 : 800,
  easing: prefersReducedMotion ? "linear" : "easeOutExpo"
});

Best Practices Summary

1. Use transforms (translate, scale, rotate) over layout properties
2. Import only needed modules for smaller bundle size
3. Use stagger for multiple element animations
4. Clean up animations on component unmount
5. Use Animatable for high-frequency updates
6. Leverage timeline for complex sequences
7. Use function-based values for dynamic animations
8. Respect reduced motion preferences
9. Consider WAAPI bridge for native performance
10. Test on lower-powered devices