Element.animate()

The Element.animate() method is a shortcut method for creating and playing an animation on an element. It returns the created Animation object instance.

Syntax

element.animate(keyframes, keyframeOptions); 

Parameters

keyframes

The keyframes object contains an array of properties you want to animate and the values to iterate over.

There are two different ways to pass keyframes to the animation:

1. An object containing key value pairs consisting of the property to animate and an array of values to iterate over.

   element.animate({
     opacity: [ 0, 1 ], // [ from, to ]
     color: [ "#fff", "#000" ] // [ from, to ]
   }, 2000);
   

2. An array of objects consisting of properties and values to iterate over.

   element.animate([ 
     { // from
       opacity: 0,
       color: "#fff"
     }, 
     { // to
       opacity: 1,
    ​   color: "#000"
     }
   ], 2000);

keyframeOptions

Either an integer representing the animation's duration (in milliseconds), or an object containing optional animation timing options, which can include those detailed in the animation timing options reference, and can also include the Additional keyframeOptions listed below.

Additional keyframeOptions

id Optional

A string with which to reference the animation.

composite Optional

Determines how values are combined between this animation and other, separate animations that do not specify their own specific composite operation. Defaults to replace.

• add dictates an additive effect, where each successive iteration builds on the last. For instance with transform, a translateX(-200px) would not override an earlier rotate(20deg) value but result in translateX(-200px) rotate(20deg).
• accumulate is similar but a little smarter: blur(2) and blur(5) become blur(7), not blur(2) blur(5).
• replace overwrites the previous value with the new one. 

iterationComposite Optional

Determines how values build from iteration to iteration in this animation. Can be set to accumulate or replace (see above). Defaults to replace.

spacing Optional

Determines how keyframes without temporal offsets should be distributed during the animation's duration. Defaults to distribute.

• distribute positions keyframes so that the difference between subsequent keyframe offsets are equal, that is to say, without any offsets, it will equally distribute the keyframes across play time.
• paced positions keyframes so that the distance between subsequent values of a specified paced property are equal, that is to say, keyframes are spaced further apart the greater the difference in their property values.

 

Return value

Returns a Animation.

Example

In the demo Down the Rabbit Hole (with the Web Animation API), we use the convenient animate() method to immediately create and play an animation on the #tunnel element to make it flow upwards, infinitely. Notice the array of objects passed as keyframes and also the timing options block.

document.getElementById("tunnel").animate([
  // keyframes
  { transform: 'translate3D(0, 0, 0)' }, 
  { transform: 'translate3D(0, -300px, 0)' }
], { 
  // timing options
  duration: 1000,
  iterations: Infinity
});

Specifications

Browser compatibility

See also

• Web Animations API
• Animation