Animation Parameters

Comprehensive reference for all animation parameters and property values

Animation parameters define how your animations behave. They can be passed to the animate() function or used when creating animation instances.

Core Parameters

targets

targets · TargetsParam · required

The element(s) to animate. This is the first argument to animate() and accepts multiple formats:

• CSS Selector: '.my-element', '#box', 'div'
• DOM Element: document.querySelector('.box')
• NodeList: document.querySelectorAll('.boxes')
• Array: [element1, element2, '.selector']
• JavaScript Object: { x: 0, y: 0 }

Timing Parameters

duration

duration · number | FunctionValue · default: "1000"

Animation duration in milliseconds.

// Fixed duration
animate('.box', { translateX: 250, duration: 2000 });

// Function-based duration
animate('.box', {
  translateX: 250,
  duration: (target, index, total) => {
    return (index + 1) * 500; // Each element takes longer
  }
});

delay

delay · number | FunctionValue · default: "0"

Delay before animation starts in milliseconds.

// Fixed delay
animate('.box', { translateX: 250, delay: 500 });

// Staggered delay
animate('.box', {
  translateX: 250,
  delay: (target, index) => index * 100
});

loopDelay

loopDelay · number · default: "0"

Delay between loop iterations in milliseconds.

animate('.box', {
  translateX: 250,
  loop: 3,
  loopDelay: 500 // Wait 500ms between each loop
});

Playback Parameters

ease

ease · EasingParam · default: "'outQuad'"

Easing function for the animation. Can be a string name or custom function.

Built-in Easings:

• 'linear', 'none'
• 'in', 'out', 'inOut'
• 'inQuad', 'outQuad', 'inOutQuad'
• 'inCubic', 'outCubic', 'inOutCubic'
• 'inQuart', 'outQuart', 'inOutQuart'
• 'inQuint', 'outQuint', 'inOutQuint'
• 'inSine', 'outSine', 'inOutSine'
• 'inExpo', 'outExpo', 'inOutExpo'
• 'inCirc', 'outCirc', 'inOutCirc'
• 'inBounce', 'outBounce', 'inOutBounce'
• 'inBack', 'outBack', 'inOutBack'
• 'inElastic', 'outElastic', 'inOutElastic'

// String easing
animate('.box', { translateX: 250, ease: 'outElastic' });

// Custom easing function
animate('.box', {
  translateX: 250,
  ease: (t) => t * t * t // Cubic ease
});

// Function-based easing
animate('.box', {
  translateX: 250,
  ease: (target, index) => {
    return index % 2 === 0 ? 'outQuad' : 'outElastic';
  }
});

playbackEase

playbackEase · EasingParam

Easing applied to the entire animation timeline playback.

animate('.box', {
  translateX: 250,
  duration: 2000,
  playbackEase: 'inOutQuad' // Eases the entire animation
});

playbackRate

playbackRate · number · default: "1"

Speed multiplier for animation playback. Values > 1 speed up, < 1 slow down.

// Play at half speed
animate('.box', {
  translateX: 250,
  playbackRate: 0.5
});

// Play at double speed
animate('.box', {
  translateX: 250,
  playbackRate: 2
});

frameRate

frameRate · number · default: "60"

Maximum frame rate for the animation in frames per second.

// Limit to 30fps
animate('.box', {
  translateX: 250,
  frameRate: 30
});

Loop Parameters

loop

loop · number | boolean · default: "false"

Number of times to loop the animation. true or negative values create infinite loops.

// Loop 3 times
animate('.box', { translateX: 250, loop: 3 });

// Loop infinitely
animate('.box', { translateX: 250, loop: true });

alternate

alternate · boolean · default: "false"

Whether to alternate direction on each loop iteration.

animate('.box', {
  translateX: 250,
  loop: true,
  alternate: true // Goes back and forth
});

reversed

reversed · boolean · default: "false"

Whether to play the animation in reverse from the start.

animate('.box', {
  translateX: 250,
  reversed: true // Plays from end to start
});

Control Parameters

autoplay

autoplay · boolean · default: "true"

Whether to automatically start the animation.

const anim = animate('.box', {
  translateX: 250,
  autoplay: false
});

// Manually start later
button.onclick = () => anim.play();

id

id · string | number

Custom identifier for the animation instance.

const anim = animate('.box', {
  id: 'myAnimation',
  translateX: 250
});

console.log(anim.id); // 'myAnimation'

Property Composition

composition

composition · 'none' | 'replace' | 'blend' · default: "'replace'"

How to compose with other animations on the same property.

• 'none': No composition, properties are independent
• 'replace': New animations replace old ones on the same property
• 'blend': New animations blend additively with existing ones

// First animation
animate('.box', { translateX: 100 });

// Second animation replaces the first
animate('.box', {
  translateX: 250,
  composition: 'replace' // Default
});

// Additive animation
animate('.box', {
  translateX: 100,
  composition: 'blend' // Adds to existing animations
});

modifier

modifier · (value: number) => number | string

Function to modify animated values before they’re applied.

animate('.box', {
  translateX: 250,
  modifier: (value) => Math.round(value) // Round to integers
});

// Add units
animate('.box', {
  translateX: 250,
  modifier: (value) => `${value}px`
});

Property Values

Animation parameters can include any animatable properties. Property values support multiple formats:

Number Values

animate('.box', {
  translateX: 250,
  opacity: 0.5,
  scale: 2
});

String Values with Units

animate('.box', {
  width: '100%',
  translateX: '250px',
  rotate: '1turn'
});

From-To Arrays

animate('.box', {
  translateX: [0, 250],    // From 0 to 250
  opacity: [1, 0]          // From 1 to 0
});

Multi-Value Arrays (Keyframes)

animate('.box', {
  translateX: [0, 100, 250, 100, 0], // Keyframe values
  duration: 2000
});

Object Values

animate('.box', {
  translateX: {
    to: 250,
    duration: 1000,
    ease: 'outQuad'
  },
  translateY: {
    from: 0,
    to: 100,
    delay: 500
  }
});

Function Values

animate('.box', {
  translateX: (target, index, total) => {
    return index * 100; // Different value per target
  },
  duration: 1000
});

Relative Values

animate('.box', {
  translateX: '+=250',  // Add 250 to current value
  translateY: '-=100',  // Subtract 100 from current value
  scale: '*=2'          // Multiply current value by 2
});

Keyframes

Duration-Based Keyframes

keyframes · DurationKeyframes

Array of keyframe objects, each with its own timing.

animate('.box', {
  keyframes: [
    { translateX: 100, duration: 500 },
    { translateY: 100, duration: 500, ease: 'outElastic' },
    { translateX: 0, duration: 500 },
    { translateY: 0, duration: 500 }
  ]
});

Percentage-Based Keyframes

keyframes · PercentageKeyframes

Object with percentage keys defining keyframe positions.

animate('.box', {
  duration: 2000,
  keyframes: {
    '0%': { translateX: 0, scale: 1 },
    '25%': { translateX: 100, scale: 1.2 },
    '50%': { translateX: 250, scale: 1.5 },
    '75%': { translateX: 100, scale: 1.2 },
    '100%': { translateX: 0, scale: 1 }
  }
});

Callbacks

onBegin

onBegin · (anim: JSAnimation) => void

Called when the animation begins playing.

animate('.box', {
  translateX: 250,
  onBegin: (anim) => {
    console.log('Animation started');
  }
});

onUpdate

onUpdate · (anim: JSAnimation) => void

Called on every frame during the animation.

animate('.box', {
  translateX: 250,
  onUpdate: (anim) => {
    console.log('Progress:', anim.progress);
    console.log('Current time:', anim.currentTime);
  }
});

onComplete

onComplete · (anim: JSAnimation) => void

Called when the animation completes.

animate('.box', {
  translateX: 250,
  onComplete: (anim) => {
    console.log('Animation finished');
    anim.targets[0].classList.add('done');
  }
});

onLoop

onLoop · (anim: JSAnimation) => void

Called when the animation loops.

animate('.box', {
  translateX: 250,
  loop: true,
  onLoop: (anim) => {
    console.log('Loop iteration:', anim.currentIteration);
  }
});

onPause

onPause · (anim: JSAnimation) => void

Called when the animation is paused.

const anim = animate('.box', {
  translateX: 250,
  onPause: (anim) => {
    console.log('Animation paused at:', anim.currentTime);
  }
});

setTimeout(() => anim.pause(), 500);

onRender

onRender · (anim: JSAnimation) => void

Called when the animation renders to the DOM.

animate('.box', {
  translateX: 250,
  onRender: (anim) => {
    console.log('Rendered');
  }
});

onBeforeUpdate

onBeforeUpdate · (anim: JSAnimation) => void

Called before each update tick.

animate('.box', {
  translateX: 250,
  onBeforeUpdate: (anim) => {
    // Prepare for update
  }
});

Function Value Parameters

Many parameters accept functions that receive target information:

type FunctionValue = (
  target: Target,   // The current target element/object
  index: number,    // Index of the target (0-based)
  length: number    // Total number of targets
) => number | string | object

Example:

animate('.box', {
  translateX: (target, index, total) => {
    // Stagger positions based on index
    return index * 100;
  },
  delay: (target, index, total) => {
    // Stagger delays
    return index * 100;
  },
  duration: (target, index, total) => {
    // Vary duration
    return 500 + (index * 100);
  },
  ease: (target, index, total) => {
    // Alternate easing
    return index % 2 === 0 ? 'outQuad' : 'outElastic';
  }
});

Related

• animate() - Main animation function
• Animation Class - Animation instance methods