W3cubDocs

/Web APIs

Element: animate() method

The Element interface's animate() method is a shortcut method which creates a new Animation, applies it to the element, then plays the animation. It returns the created Animation object instance.

Note: Elements can have multiple animations applied to them. You can get a list of the animations that affect an element by calling Element.getAnimations().

Syntax

js

animate(keyframes, options)

Parameters

keyframes

Either an array of keyframe objects, or a keyframe object whose properties are arrays of values to iterate over. See Keyframe Formats for more details.

options

Either an integer representing the animation's duration (in milliseconds), or an Object containing one or more timing properties described in the KeyframeEffect() options parameter and/or the following options:

id Optional

A property unique to animate(): A string with which to reference the animation.

rangeEnd Optional

Specifies the end of an animation's attachment range along its timeline, i.e. where along the timeline an animation will end. The JavaScript equivalent of the CSS animation-range-end property. rangeEnd can take several different value types, as follows:

  • A string that can be normal (meaning no change to the animation's attachment range), a CSS <length-percentage> representing an offset, a <timeline-range-name>, or a <timeline-range-name> with a <length-percentage> following it. For example:
    "normal"
    "entry"
    "cover 100%"
    
    See animation-range for a detailed description of the available values. Also check out the View Timeline Ranges Visualizer, which shows exactly what the different values mean in an easy visual format.
  • An object containing rangeName (a string) and offset (a CSSNumericValue) properties representing a <timeline-range-name> and <length-percentage>, as described in the previous bullet. For example:

    js

    {
      rangeName: 'entry',
      offset: CSS.percent('100'),
    }
    
  • A CSSNumericValue representing an offset, for example:

    js

    CSS.percent("100");
    
rangeStart Optional

Specifies the start of an animation's attachment range along its timeline, i.e. where along the timeline an animation will start. The JavaScript equivalent of the CSS animation-range-start property. rangeStart can take the same value types as rangeEnd.

timeline Optional

A property unique to animate(): The AnimationTimeline to associate with the animation. Defaults to Document.timeline. The JavaScript equivalent of the CSS animation-timeline property.

Return value

Returns an Animation.

Examples

Rotating and scaling

In this example we use the animate() method to rotate and scale an element.

HTML

html

<div class="newspaper">Spinning newspaper<br />causes dizziness</div>

CSS

css

html,
body {
  height: 100%;
}

body {
  display: flex;
  justify-content: center;
  align-items: center;
  background-color: black;
}

.newspaper {
  padding: 0.5rem;
  text-transform: uppercase;
  text-align: center;
  background-color: white;
  cursor: pointer;
}

JavaScript

js

const newspaperSpinning = [
  { transform: "rotate(0) scale(1)" },
  { transform: "rotate(360deg) scale(0)" },
];

const newspaperTiming = {
  duration: 2000,
  iterations: 1,
};

const newspaper = document.querySelector(".newspaper");

newspaper.addEventListener("click", () => {
  newspaper.animate(newspaperSpinning, newspaperTiming);
});

Result

Down the Rabbit Hole demo

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.

js

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

Implicit to/from keyframes

In newer browser versions, you are able to set a beginning or end state for an animation only (i.e. a single keyframe), and the browser will infer the other end of the animation if it is able to. For example, consider this simple animation — the Keyframe object looks like so:

js

let rotate360 = [{ transform: "rotate(360deg)" }];

We have only specified the end state of the animation, and the beginning state is implied.

timeline, rangeStart, and rangeEnd

Typical usage of the timeline, rangeStart, and rangeEnd properties might look like this:

js

const img = document.querySelector("img");

const timeline = new ViewTimeline({
  subject: img,
  axis: "block",
});

img.animate(
  {
    opacity: [0, 1],
    transform: ["scaleX(0)", "scaleX(1)"],
  },
  {
    fill: "both",
    duration: 1,
    timeline,
    rangeStart: "cover 0%",
    rangeEnd: "cover 100%",
  },
);

Specifications

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
animate 36 79 48 No 23 13.1 37 36 48 24 13.4 3.0
implicit_tofrom 84 84 75 No 70
13.1Implementation seems somewhat buggy. More information will follow when available.
84 84 No 60
13.4Implementation seems somewhat buggy. More information will follow when available.
14.0
options_composite_parameter 84 84 80 No 70 16 84 84 80 60 16 14.0
options_id_parameter 50 79 48 No 37 13.1 50 50 48 37 13.4 5.0
options_iterationComposite_parameter No No 80 No No No No No 80 No No No
options_pseudoElement_parameter 84 84 75 No 70 14 84 84 No 60 14 14.0
options_rangeEnd_parameter 115 115 No No 101 No 115 115 No No No No
options_rangeStart_parameter 115 115 No No 101 No 115 115 No No No No
options_timeline_parameter 85 85 No No 71 16 85 85 No 60 16 14.0

See also

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Web/API/Element/animate