Element.animate()

 

This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

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

Specification Status Comment
Web Animations
The definition of 'animate()' in that specification.
Working Draft Initial definition

Browser compatibility

Feature Chrome Edge Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support 39 ? 48.0 (48.0) ? ? ?
Feature Android Android Webview Chrome for Android Firefox Mobile (Gecko) Firefox OS IE Mobile Opera Mobile Safari Mobile
Basic support ? ? ? 48.0 (48.0) ? ? ? ?

See also

Document Tags and Contributors

 Last updated by: Sebastianz,