Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

Animation.play(): starting and resuming animations

Animation.play() starts or resumes an existing animation. It neither creates another animation nor returns a promise.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

animation.play()

animation.play() takes no arguments and returns undefined. For an animation on the document timeline (document.timeline), as in the example, play() at a positive effective playback rate preserves the current position if the current time is nonnegative and before the end of the effect. At that rate, if the current time is at or beyond the effect end, play() seeks back to the beginning, even if the animation is paused.

After a call to updatePlaybackRate(), the effective playback rate used by play() can differ from playbackRate: if a rate change is still pending, play() uses the pending rate. On a document timeline, a pending negative rate can therefore make play() seek from time zero to the end of a finite effect even while playbackRate still reports a positive value.

Playback startup can await an asynchronous task. animation.ready signals readiness, whereas animation.finished signals completion. Calling play() itself waits for neither.

This is a Web API, not an ECMAScript feature. Check target-browser support; Node 24 does not establish it. The example shows resuming from an in-range time, not the case of a pending negative rate. It uses an effect without a target element and draws nothing.

Examples

const effect = new KeyframeEffect(null, [], { duration: 1000 });
const animation = new Animation(effect, document.timeline);

animation.currentTime = 400;
const result = animation.play();
console.log(result === undefined, animation.currentTime);

animation.finish();
console.log(animation.playState, animation.currentTime);

Result

true 400
finished 1000

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources