Web Animations

Editor’s Draft,

More details about this document
This version:
https://drafts.csswg.org/web-animations-1/
Latest published version:
https://www.w3.org/TR/web-animations-1/
Previous Versions:
Version History:
https://github.com/w3c/csswg-drafts/commits/main/web-animations-1
Test Suite:
https://github.com/web-platform-tests/wpt/tree/master/web-animations
Feedback:
CSSWG Issues Repository
Inline In Spec
Editors:
(Invited Expert)
(Google)
(Google)
(Apple Inc)
Former Editors:
(Google)
(Google)
(Google)
(Google)
Suggest an Edit for this Spec:
GitHub Editor
Participate:
Fix the text through GitHub
Join the "waapi" channel on the Animation at Work slack
IRC: #webanimations on W3C’s IRC

Abstract

This specification defines a model for synchronization and timing of changes to the presentation of a Web page. This specification also defines an application programming interface for interacting with this model and it is expected that further specifications will define declarative means for exposing these features.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

Please send feedback by filing issues in GitHub (preferred), including the spec code “web-animations” in the title, like this: “[web-animations] …summary of comment…”. All issues and comments are archived. Alternately, feedback can be sent to the (archived) public mailing list www-style@w3.org.

This document is governed by the 2 November 2021 W3C Process Document.

1. Introduction

This section is non-normative

Web Animations defines a model for supporting animation and synchronization on the Web platform. It is intended that other specifications will build on this model and expose its features through declarative means. In addition, this specification also defines a programming interface to the model that may be implemented by user agents that provide support for scripting.

1.1. Use cases

The Web Animations model is intended to provide the features necessary for expressing CSS Transitions [CSS-TRANSITIONS-1], CSS Animations [CSS-ANIMATIONS-1], and SVG [SVG11]. As such, the use cases of Web Animations model is the union of use cases for those three specifications.

The use cases for the programming interface include the following:

Inspecting running animations

Often Web applications must wait for certain animated effects to complete before updating some state. The programming interface in this specification allows such applications to wait for all currently running animation to complete, regardless of whether they are defined by CSS Transitions, CSS Animations, SVG animations, or created directly using the programming interface.

// Wait until all animations have finished before removing the element
Promise.all(
  elem.getAnimations().map(animation => animation.finished)
).then(() => elem.remove());

Alternatively, applications may wish to query the playback state of animations without waiting.

const isAnimating = elem.getAnimations().some(
  animation => animation.playState === 'running'
);
Controlling running animations

It is sometimes useful to perform playback control on animations so that they can respond to external inputs. For example, it may be necessary to pause all existing animations before displaying a modal dialog so that they do not distract the user’s attention.

// Pause all existing animations in the document
for (const animation of document.getAnimations()) {
  animation.pause()
}
Creating animations from script

While it is possible to use ECMAScript to perform animation using requestAnimationFrame [HTML], such animations behave differently to declarative animation in terms of how they are represented in the CSS cascade and the performance optimizations that are possible such as performing the animation on a separate thread. Using the Web Animations programming interface, it is possible to create animations from script that have the same behavior and performance characteristics as declarative animations.

// Fade out quickly
elem.animate({ transform: 'scale(0)', opacity: 0 }, 300);
Animation debugging

In a complex application, it may be difficult to determine how an element arrived in its present state. The Web Animations programming interface may be used to inspect running animations to answer questions such as, "Why is the opacity of this element changing?"

// Print the id of any opacity animations on elem
for (const animation of elem.getAnimations()) {
  if (
    animation.effect instanceof KeyframeEffect &&
    animation.effect
      .getKeyframes()
      .some(frame => frame.hasOwnProperty('opacity'))
  ) {
    console.log(animation.id);
  }
}

Likewise, in order to fine tune animations, it is often necessary to reduce their playback rate and replay them.

// Slow down and replay any transform animations
const transformAnimations = elem.getAnimations().filter(
  animation =>
    animation.effect instanceof KeyframeEffect &&
    animation.effect.getKeyframes().some(
      frame => frame.hasOwnProperty('transform')
    )
);

for (const animation of transformAnimations) {
  animation.currentTime = 0;
  animation.updatePlaybackRate(0.5);
}
Testing animations

In order to test applications that make use of animations it is often impractical to wait for such animations to run to completion. Rather, it is desirable to seek the animations to specific times.

// Seek to the half-way point of an animation and check that the opacity is 50%
for (const animation of elem.getAnimations()) {
  const { delay, activeDuration } = animation.effect.getComputedTiming();
  animation.currentTime = delay + activeDuration / 2;
}
assert.strictEqual(getComputedStyle(elem).opacity, '0.5');

// Check that the loading screen is hidden after the animations finish
for (const animation of elem.getAnimations()) {
  animation.finish();
}
// Wait one frame so that event handlers have a chance to run
requestAnimationFrame(() => {
  assert.strictEqual(
    getComputedStyle(document.querySelector('#loading')).display, 'none');
});

1.2. Relationship to other specifications

CSS Transitions [CSS-TRANSITIONS-1], CSS Animations [CSS-ANIMATIONS-1], and SVG [SVG11] all provide mechanisms that generate animated content on a Web page. Although the three specifications provide many similar features, they are described in different terms. This specification proposes an abstract animation model that encompasses the common features of all three specifications. This model is backwards-compatible with the current behavior of these specifications such that they can be defined in terms of this model without any observable change.

The animation features in SVG 1.1 are defined in terms of SMIL Animation [SMIL-ANIMATION]. It is intended that by defining SVG’s animation features in terms of the Web Animations model, the dependency between SVG and SMIL Animation can be removed.

As with animation frame callbacks (commonly referred to as "requestAnimationFrame") [HTML], the programming interface component of this specification allows animations to be created from script. The animations created using the interface defined in this specification, however, once created, are executed entirely by the user agent meaning they share the same performance characteristics as animations defined by markup. Using this interface it is possible to create animations from script in a simpler and more performant manner.

The time values used within the programming interface correspond with those used in animation frame callbacks [HTML] and their execution order is defined such that the two interfaces can be used simultaneously without conflict.

The programming interface component of this specification makes some additions to interfaces defined in HTML [HTML].

1.3. Overview of this specification

This specification begins by defining an abstract model for animation. This is followed by a programming interface defined in terms of the abstract model. The programming interface is defined in terms of the abstract model and is only relevant to user agents that provide scripting support.

2. Specification conventions

This specification begins by describing abstract concepts such as animations and animation effects and properties that belong to them such as their playback rate or iteration duration. In addition to these properties, there are often specific procedures for updating these properties such as the procedure to set the playback rate or the procedure to set the start time of an animation.

Where this specification does not specifically link to a procedure, text that requires the user agent to update a property such as, "make animation’s start time unresolved", should be understood to refer to updating the property directly without invoking any related procedure.

Further documentation conventions that are not specific to this specification are described in Document conventions.

3. Web Animations model overview

This section is non-normative

At a glance, the Web Animations model consists of two largely independent pieces, a timing model and an animation model. The role of these pieces is as follows:

Timing model

Takes a moment in time and converts it to a proportional distance within a single iteration of an animation called the iteration progress. The iteration index is also recorded since some animations vary each time they repeat.

Animation model

Takes the iteration progress values and iteration indices produced by the timing model and converts them into a series of values to apply to the target properties.

Graphically, this flow can be represented as follows:

Overview of the operation of the Web Animations model.
Overview of the operation of the Web Animations model.
The current time is input to the timing model which produces an iteration progress value and an iteration index.
These parameters are used as input to the animation model which produces the values to apply.

For example, consider an animation that:

The first three points apply to the timing model. At a time of 6 seconds, it will calculate that the animation should be half-way through its second iteration and produces the result 0.5. The animation model then uses that information to calculate a width.

This specification begins with the timing model and then proceeds to the animation model.

4. Timing model

This section describes and defines the behavior of the Web Animations timing model.

4.1. Timing model overview

This section is non-normative

Two features characterize the Web Animations timing model: it is stateless and it is hierarchical.

4.1.1. Stateless

The Web Animations timing model operates by taking an input time and producing an output iteration progress. Since the output is based solely on the input time and is independent of previous inputs, the model may be described as stateless. This gives the model the following properties:

Frame-rate independent

Since the output is independent of previous inputs, the rate at which the model is updated will not affect its progress. Provided the input times are proportional to the progress of real-world time, animations will progress at an identical rate regardless of the capabilities of the device running them.

Direction-agnostic

Since the sequence of inputs is insignificant, the model is directionless. This means that the model can be updated to an arbitrary moment without requiring any specialized handling.

Constant-time seeking

Since each input is independent of the previous input, the processing required to perform a seek operation, even far into the future, is at least potentially constant.

There are a few exceptions to the stateless behavior of the timing model.

Firstly, a number of methods defined in the programming interface to the model provide play control such as pausing an animation. These methods are defined in terms of the time at which they are called and are therefore stative. These methods are provided primarily for convenience and are not part of the core timing model but are layered on top.

Similarly, the finishing behavior of animations means that dynamic changes to the end time of the media (associated effect) of an animation may produce a different result depending on when the change occurs. This behavior is somewhat unfortunate but has been deemed intuitive and consistent with HTML. As a result, the model can only truly be described as stateless in the absence of dynamic changes to its timing properties.

Finally, each time the model is updated, it can be considered to establish a temporary state. While this temporary state affects the values returned from the programming interface, it has no influence on the subsequent updates and hence does not conflict with the stateless qualities described above.

4.1.2. Hierarchical

The other characteristic feature of the timing model is that time is inherited. Time begins at a timeline and cascades down a number of steps to each animation effect. At each step, time may be shifted backwards and forwards, scaled, reversed, paused, and repeated.

A hierarchy of timing nodes
A hierarchy of timing nodes. Each node in the tree derives its time from its parent node.

In this level of the specification the hierarchy is shallow. A subsequent level of this specification will introduce the concept of group effects which allows for deeper timing hierarchies.

4.2. Time values

Timing is based on a hierarchy of time relationships between timing nodes. Parent nodes provide timing information to their child nodes in the form of time values.

A time value is a real number which nominally represents a number of milliseconds from some moment. The connection between time values and wall-clock milliseconds may be obscured by any number of transformations applied to the value as it passes through the time hierarchy.

In the future there may be timelines that are based on scroll position or UI gestures in which case the connection between time values and milliseconds will be weakened even further.

A time value may also be unresolved if, for example, a timing node is not in a state to produce a time value.

4.3. Timelines

A timeline provides a source of time values for the purpose of synchronization.

At any given moment, a timeline has a single current time value known simply as the timeline’s current time.

A timeline may not always be able to return a meaningful time value, but only an unresolved time value. For example, it may be defined relative to a moment that has yet to occur, such as the firing of a document’s load event. A timeline is considered to be inactive when its time value is unresolved.

A timeline is monotonically increasing if its reported current time is always greater than or equal than its previously reported current time.

Specific types of timelines may define a procedure to convert a timeline time to an origin-relative time for time value time, so that the time values produced by wallclock-based timelines can be compared.

A timeline may be associated with a document.

When asked to update animations and send events for a Document doc at timestamp now, run these steps:

  1. Update the current time of all timelines associated with doc passing now as the timestamp.

    Due to the hierarchical nature of the timing model, updating the current time of a timeline also involves:

  2. Remove replaced animations for doc.

  3. Perform a microtask checkpoint.

    Note: This is to ensure that any microtasks queued up as a result of resolving or rejecting Promise objects as part of updating timelines in the previous step, run their callbacks prior to dispatching animation events.

  4. Let events to dispatch be a copy of doc’s pending animation event queue.

  5. Clear doc’s pending animation event queue.

  6. Perform a stable sort of the animation events in events to dispatch as follows:

    1. Sort the events by their scheduled event time such that events that were scheduled to occur earlier, sort before events scheduled to occur later and events whose scheduled event time is unresolved sort before events with a resolved scheduled event time.

    2. Within events with equal scheduled event times, sort by their composite order.

    Note: The purpose of sorting events is to ensure that, as best possible, even on devices with differing capabilities and hence different frame rates, events are dispatched in a consistent order.

    Note: The requirement for the sort to be a stable sort is because sometimes events may be queued with the same scheduled event time. For example, a CSS animation with a duration of zero, may dispatch both an animationstart and an animationend event and the order of these events should be preserved.

  7. Dispatch each of the events in events to dispatch at their corresponding target using the order established in the previous step.

It is often convenient to describe each time this procedure is invoked as establishing a new animation frame. Changes to the timing properties of animations or animation effects, or the addition and removal of the objects may cause the output of the timing or animation model to change, but these operations in themselves do not create a new animation frame, rather they merely update the current animation frame.

4.3.1. Document timelines

A document timeline is a type of timeline that is associated with a document and whose current time is calculated as a fixed offset from the now timestamp provided each time the update animations and send events procedure is run. This fixed offset is referred to as the document timeline’s origin time.

There must be a better term than "origin time"— it’s too similar to "time origin". [Issue #2079]

Prior to establishing the time origin for its associated document, a document timeline is inactive.

After a document timeline becomes active, it is monotonically increasing.

A document timeline that is associated with a Document which is not an active document is also considered to be inactive.

To convert a timeline time, timeline time, to an origin-relative time for a document timeline, timeline, return the sum of the timeline time and timeline’s origin time. If timeline is inactive, return an unresolved time value.

4.3.2. The default document timeline

Each Document has a document timeline called the default document timeline. The default document timeline is unique to each document and persists for the lifetime of the document including calls to document.open() [HTML].

The default document timeline has an origin time of zero.

This section is non-normative

Since no scaling is applied to the now timestamp values provided to document timelines, the time values it produces will be proportional to wall-clock milliseconds.

Furthermore, since the time values of the default document timeline have a zero offset from the time origin, document.timeline.currentTime will roughly correspond to Performance.now() [HR-TIME] with the exception that document.timeline.currentTime does not change in between calls to the update animations and send events procedure.

4.4. Animations

This section is non-normative

The children of a timeline are called animations. An animation takes an animation effect which is a static description of some timed behavior and binds it to a timeline so that it runs. An animation also allows run-time control of the connection between the animation effect and its timeline by providing pausing, seeking, and speed control. The relationship between an animation and an animation effect is analogous to that of a DVD player and a DVD.

An animation connects a single animation effect, called its associated effect, to a timeline and provides playback control. Both of these associations are optional and configurable such that an animation may have no associated effect or timeline at a given moment.

An animation’s document for timing is the Document with which its timeline is associated. If an animation is not associated with a timeline, or its timeline is not associated with a document, then it has no document for timing.

An animation’s start time is the time value of its timeline when its associated effect is scheduled to begin playback. An animation’s start time is initially unresolved.

An animation also maintains a hold time time value which is used to fix the animation’s output time value, called its current time, in circumstances such as pausing. The hold time is initially unresolved.

In order to establish the relative ordering of conflicting animations, animations are appended to a global animation list in the order in which they are created. Certain classes of animations, however, may provide alternative means of ordering animations (see § 5.4.1 Animation classes).

4.4.1. Setting the timeline of an animation

The procedure to set the timeline of an animation, animation, to new timeline which may be null, is as follows:

  1. Let old timeline be the current timeline of animation, if any.

  2. If new timeline is the same object as old timeline, abort this procedure.

  3. Let the timeline of animation be new timeline.

  4. If the start time of animation is resolved, make animation’s hold time unresolved.

    Note: This step ensures that the finished play state of animation is not "sticky" but is re-evaluated based on its updated current time.

  5. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

4.4.2. Setting the associated effect of an animation

The procedure to set the associated effect of an animation, animation, to new effect which may be null, is as follows:

  1. Let old effect be the current associated effect of animation, if any.

  2. If new effect is the same object as old effect, abort this procedure.

  3. If animation has a pending pause task, reschedule that task to run as soon as animation is ready.

  4. If animation has a pending play task, reschedule that task to run as soon as animation is ready to play new effect.

  5. If new effect is not null and if new effect is the associated effect of another animation, previous animation, run the procedure to set the associated effect of an animation (this procedure) on previous animation passing null as new effect.

  6. Let the associated effect of animation be new effect.

  7. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

The procedure to reset an animation’s pending tasks for animation is as follows:

  1. If animation does not have a pending play task or a pending pause task, abort this procedure.

  2. If animation has a pending play task, cancel that task.

  3. If animation has a pending pause task, cancel that task.

  4. Apply any pending playback rate on animation.

  5. Reject animation’s current ready promise with a DOMException named "AbortError".

  6. Set the [[PromiseIsHandled]] internal slot of animation’s current ready promise to true.

  7. Let animation’s current ready promise be the result of creating a new resolved Promise object with value animation in the relevant Realm of animation.

4.4.3. The current time of an animation

Animations provide a time value to their associated effect called the animation’s current time.

The current time is calculated from the first matching condition from below:

If the animation’s hold time is resolved,

The current time is the animation’s hold time.

If any of the following are true:

  1. the animation has no associated timeline, or

  2. the associated timeline is inactive, or

  3. the animation’s start time is unresolved.

The current time is an unresolved time value.

Otherwise,
current time = (timeline time - start time) × playback rate

Where timeline time is the current time value of the associated timeline. The playback rate value is defined in § 4.4.15 Speed control.

4.4.4. Setting the current time of an animation

The current time of an animation can be set to a new value to seek the animation. The procedure for setting the current time is defined in two parts.

The procedure to silently set the current time of an animation, animation, to seek time is as follows:

  1. If seek time is an unresolved time value, then perform the following steps.

    1. If the current time is resolved, then throw a TypeError.

    2. Abort these steps.

  2. Update either animation’s hold time or start time as follows:

    If any of the following conditions are true:

    Set animation’s hold time to seek time.

    Otherwise,

    Set animation’s start time to the result of evaluating timeline time - (seek time / playback rate) where timeline time is the current time value of timeline associated with animation.

  3. If animation has no associated timeline or the associated timeline is inactive, make animation’s start time unresolved.

    This preserves the invariant that when we don’t have an active timeline it is only possible to set either the start time or the animation’s current time.

  4. Make animation’s previous current time unresolved.

The procedure to set the current time of an animation, animation, to seek time is as follows:

  1. Run the steps to silently set the current time of animation to seek time.

  2. If animation has a pending pause task, synchronously complete the pause operation by performing the following steps:

    1. Set animation’s hold time to seek time.

    2. Apply any pending playback rate to animation.

    3. Make animation’s start time unresolved.

    4. Cancel the pending pause task.

    5. Resolve animation’s current ready promise with animation.

  3. Run the procedure to update an animation’s finished state for animation with the did seek flag set to true, and the synchronously notify flag set to false.

4.4.5. Setting the start time of an animation

The procedure to set the start time of animation, animation, to new start time, is as follows:

  1. Let timeline time be the current time value of the timeline that animation is associated with. If there is no timeline associated with animation or the associated timeline is inactive, let the timeline time be unresolved.

  2. If timeline time is unresolved and new start time is resolved, make animation’s hold time unresolved.

    This preserves the invariant that when we don’t have an active timeline it is only possible to set either the start time or the animation’s current time.

  3. Let previous current time be animation’s current time.

    Note: This is the current time after applying the changes from the previous step which may cause the current time to become unresolved.

  4. Apply any pending playback rate on animation.

  5. Set animation’s start time to new start time.

  6. Update animation’s hold time based on the first matching condition from the following,

    If new start time is resolved,

    If animation’s playback rate is not zero, make animation’s hold time unresolved.

    Otherwise (new start time is unresolved),

    Set animation’s hold time to previous current time even if previous current time is unresolved.

  7. If animation has a pending play task or a pending pause task, cancel that task and resolve animation’s current ready promise with animation.

  8. Run the procedure to update an animation’s finished state for animation with the did seek flag set to true, and the synchronously notify flag set to false.

4.4.6. Waiting for the associated effect

This section is non-normative

Some operations performed by an animation may not occur instantaneously. For example, some user agents may delegate the playback of an animation to a separate process or to specialized graphics hardware each of which may incur some setup overhead.

If such an animation is timed from the moment when the animation was triggered there may be a significant jump between the first and second frames of the animation corresponding to the setup time involved.

To avoid this problem, Web Animations typically begins timing animations from the moment when the first frame of the animation is complete. This is represented by an unresolved start time on the animation which becomes resolved when the animation is ready. Content may opt out of this behavior by setting the start time to a resolved time value.

An animation is ready at the first moment where both of the following conditions are true:

4.4.7. The current ready promise

Each animation has a current ready promise. The current ready promise is initially a resolved Promise created using the procedure to create a new resolved Promise with the animation itself as its value and created in the relevant Realm of the animation.

The object is replaced with a new Promise object every time the animation queues a pending play task or a pending pause task when it previously did not have a pending task, or when the animation is canceled (see § 4.4.14 Canceling an animation).

Note that since the same object is used for both pending play and pending pause requests, authors are advised to check the state of the animation when the Promise object is resolved.

For example, in the following code fragment, the state of the animation will be running when the current ready promise is resolved. This is because the play operation occurs while a pending play task is still queued and hence the current ready promise is re-used.

animation.pause();
animation.ready.then(function() {
  // Displays 'running'
  alert(animation.playState);
});
animation.play();

4.4.8. Playing an animation

The procedure to play an animation, animation, given a flag auto-rewind, is as follows:

  1. Let aborted pause be a boolean flag that is true if animation has a pending pause task, and false otherwise.

  2. Let has pending ready promise be a boolean flag that is initially false.

  3. Let seek time be a time value that is initially unresolved.

  4. If the auto-rewind flag is true, perform the steps corresponding to the first matching condition from the following, if any:

    If animation’s effective playback rate ≥ 0, and animation’s current time is either:

    Set seek time to zero.

    If animation’s effective playback rate < 0, and animation’s current time is either:

    If associated effect end is positive infinity,

    throw an "InvalidStateError" DOMException and abort these steps.

    Otherwise,

    Set seek time to animation’s associated effect end.

  5. If the following three conditions are all satisfied:

    set seek time to zero.

    Note: The above step ensures that this procedure will play an idle animation regardless of the setting of the auto-rewind flag.

  6. Let has finite timeline be true if animation has an associated timeline that is not monotonically increasing.

  7. If seek time is resolved,

    If has finite timeline is true,
    1. Set animation’s start time to seek time.

    2. Let animation’s hold time be unresolved.

    3. Apply any pending playback rate on animation.

    Otherwise,

    Set animation’s hold time to seek time.

  8. If animation’s hold time is resolved, let its start time be unresolved.

  9. If animation has a pending play task or a pending pause task,

    1. Cancel that task.

    2. Set has pending ready promise to true.

  10. If the following four conditions are all satisfied:

    abort this procedure.

  11. If has pending ready promise is false, let animation’s current ready promise be a new promise in the relevant Realm of animation.

  12. Schedule a task to run as soon as animation is ready. The task shall perform the following steps:

    1. Assert that at least one of animation’s start time or hold time is resolved.

    2. Let ready time be the time value of the timeline associated with animation at the moment when animation became ready.

    3. Perform the steps corresponding to the first matching condition below, if any:

      If animation’s hold time is resolved,
      1. Apply any pending playback rate on animation.

      2. Let new start time be the result of evaluating ready time - hold time / playback rate for animation. If the playback rate is zero, let new start time be simply ready time.

      3. Set the start time of animation to new start time.

      4. If animation’s playback rate is not 0, make animation’s hold time unresolved.

      If animation’s start time is resolved and animation has a pending playback rate,
      1. Let current time to match be the result of evaluating (ready time - start time) × playback rate for animation.

      2. Apply any pending playback rate on animation.

      3. If animation’s playback rate is zero, let animation’s hold time be current time to match.

      4. Let new start time be the result of evaluating ready time - current time to match / playback rate for animation. If the playback rate is zero, let new start time be simply ready time.

      5. Set the start time of animation to new start time.

    4. Resolve animation’s current ready promise with animation.

    5. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

      Note that the order of the above two steps is important since it means that an animation with zero-length associated effect will resolve its current ready promise before its current finished promise.

    So long as the above task is scheduled but has yet to run, animation is described as having a pending play task. While the task is running, however, animation does not have a pending play task.

    If a user agent determines that animation is immediately ready, it may schedule the above task as a microtask such that it runs at the next microtask checkpoint, but it must not perform the task synchronously.

    The above requirement to run the pending play task asynchronously ensures that code such as the following behaves consistently between implementations:

    animation.play();
    animation.ready.then(
      () => { console.log('Playback commenced'); },
      () => { console.log('Playback was canceled'); }
    );
    // Suppose some condition requires playback to be canceled...
    animation.cancel();
    // "Playback was canceled" will be printed to the console.
    

    In the above code, were the pending play task run synchronously, the current ready promise would not be rejected.

  13. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

4.4.9. Pausing an animation

Whenever an animation has an unresolved start time, its current time will be suspended.

As with playing an animation, pausing may not happen instantaneously (see § 4.4.6 Waiting for the associated effect). For example, if animation is performed by a separate process, it may be necessary to synchronize the current time to ensure that it reflects the state drawn by the animation process.

The procedure to pause an animation, animation, is as follows:

  1. If animation has a pending pause task, abort these steps.

  2. If the play state of animation is paused, abort these steps.

  3. Let seek time be a time value that is initially unresolved.

  4. Let has finite timeline be true if animation has an associated timeline that is not monotonically increasing.

  5. If the animation’s current time is unresolved, perform the steps according to the first matching condition from below:

    If animation’s playback rate is ≥ 0,

    Set seek time to zero.

    Otherwise,
    If associated effect end for animation is positive infinity,

    throw an "InvalidStateError" DOMException and abort these steps.

    Otherwise,

    Set seek time to animation’s associated effect end.

  6. If seek time is resolved,

    If has finite timeline is true,

    Set animation’s start time to seek time.

    Otherwise,

    Set animation’s hold time to seek time.

  7. Let has pending ready promise be a boolean flag that is initially false.

  8. If animation has a pending play task, cancel that task and let has pending ready promise be true.

  9. If has pending ready promise is false, set animation’s current ready promise to a new promise in the relevant Realm of animation.

  10. Schedule a task to be executed at the first possible moment where both of the following conditions are true:

    • the user agent has performed any processing necessary to suspend the playback of animation’s associated effect, if any.

    • the animation is associated with a timeline that is not inactive.

    The task shall perform the following steps:

    1. Let ready time be the time value of the timeline associated with animation at the moment when the user agent completed processing necessary to suspend playback of animation’s associated effect.

    2. If animation’s start time is resolved and its hold time is not resolved, let animation’s hold time be the result of evaluating (ready time - start time) × playback rate.

      Note: The hold time might be already set if the animation is finished, or if the animation has a pending play task. In either case we want to preserve the hold time as we enter the paused state.

    3. Apply any pending playback rate on animation.

    4. Make animation’s start time unresolved.

    5. Resolve animation’s current ready promise with animation.

    6. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

    So long as the above task is scheduled but has yet to run, animation is described as having a pending pause task. While the task is running, however, animation does not have a pending pause task.

    As with the pending play task, the user agent must run the pending pause task asynchronously, although that may be as soon as the next microtask checkpoint.

  11. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

4.4.10. Reaching the end

This section is non-normative

DVD players or cassette players typically continue playing until they reach the end of their media at which point they stop. If such players are able to play in reverse, they typically stop playing when they reach the beginning of their media. In order to emulate this behavior and to provide consistency with HTML’s media elements [HTML], the current time of Web Animations' animations do not play forwards beyond the end time of their associated effect or play backwards past time zero.

An animation that has reached the natural boundary of its playback range is said to have finished.

Graphically, the effect of limiting the current time is shown below.

The effect of limiting the current time of an animation.
The effect of limiting the current time of an animation with a start time of 1s, an associated effect of length 3s, and a positive playback rate. After the current time of the animation reaches the end of the associated effect, it is capped at 3s.

It is possible, however, to seek the current time of an animation to a time past the end of the associated effect. When doing so, the current time will not progress but the animation will act as if it had been paused at the seeked time.

This allows, for example, seeking the current time of an animation with no associated effect to 5s. If associated effect with an end time later than 5s is later associated with the animation, playback will begin from the 5s mark.

Similar behavior to the above scenario may arise when the length of an animation’s associated effect changes.

Similarly, when the playback rate is negative, the current time does not progress past time zero.

4.4.11. The current finished promise

Each animation has a current finished promise. The current finished promise is initially a pending Promise object.

The object is replaced with a new promise every time the animation leaves the finished play state.

4.4.12. Updating the finished state

For an animation with a positive playback rate, the current time continues to increase until it reaches the associated effect end.

The associated effect end of an animation is equal to the end time of the animation’s associated effect. If the animation has no associated effect, the associated effect end is zero.

For an animation with a negative playback rate, the current time continues to decrease until it reaches zero.

A running animation that has reached this boundary (or overshot it) and has a resolved start time is said to be finished.

The crossing of this boundary is checked on each modification to the animation object using the procedure to update an animation’s finished state defined below. This procedure is also run as part of the update animations and send events procedure. In both cases the did seek flag, defined below, is set to false.

For each animation, the user agent maintains a previous current time time value that is originally unresolved.

Whilst during normal playback the current time of an animation is limited to the boundaries described above, it is possible to seek the current time of an animation to times outside those boundaries using the procedure to set the current time of an animation.

The procedure to update an animation’s finished state for animation, given a flag did seek (to indicate if the update is being performed after setting the current time), and a flag synchronously notify (to indicate the update was called in a context where we expect finished event queueing and finished promise resolution to happen immediately, if at all) is as follows:

  1. Let the unconstrained current time be the result of calculating the current time substituting an unresolved time value for the hold time if did seek is false. If did seek is true, the unconstrained current time is equal to the current time.

    Note: This is required to accommodate timelines that may change direction. Without this definition, a once-finished animation would remain finished even when its timeline progresses in the opposite direction.

  2. If all three of the following conditions are true,

    then update animation’s hold time based on the first matching condition for animation from below, if any:

    If playback rate > 0 and unconstrained current time is greater than or equal to associated effect end,

    If did seek is true, let the hold time be the value of unconstrained current time.

    If did seek is false, let the hold time be the maximum value of previous current time and associated effect end. If the previous current time is unresolved, let the hold time be associated effect end.

    If playback rate < 0 and unconstrained current time is less than or equal to 0,

    If did seek is true, let the hold time be the value of unconstrained current time.

    If did seek is false, let the hold time be the minimum value of previous current time and zero. If the previous current time is unresolved, let the hold time be zero.

    If playback rate ≠ 0, and animation is associated with an active timeline,

    Perform the following steps:

    1. If did seek is true and the hold time is resolved, let animation’s start time be equal to the result of evaluating timeline time - (hold time / playback rate) where timeline time is the current time value of timeline associated with animation.

    2. Let the hold time be unresolved.

  3. Set the previous current time of animation be the result of calculating its current time.

  4. Let current finished state be true if the play state of animation is finished. Otherwise, let it be false.

  5. If current finished state is true and the current finished promise is not yet resolved, perform the following steps:

    1. Let finish notification steps refer to the following procedure:

      1. If animation’s play state is not equal to finished, abort these steps.

      2. Resolve animation’s current finished promise object with animation.

      3. Create an AnimationPlaybackEvent, finishEvent.

      4. Set finishEvent’s type attribute to finish.

      5. Set finishEvent’s currentTime attribute to the current time of animation.

      6. Set finishEvent’s timelineTime attribute to the current time of the timeline with which animation is associated. If animation is not associated with a timeline, or the timeline is inactive, let timelineTime be null.

      7. If animation has a document for timing, then append finishEvent to its document for timing's pending animation event queue along with its target, animation. For the scheduled event time, use the result of converting animation’s associated effect end to an origin-relative time.

        Otherwise, queue a task to dispatch finishEvent at animation. The task source for this task is the DOM manipulation task source.

    2. If synchronously notify is true, cancel any queued microtask to run the finish notification steps for this animation, and run the finish notification steps immediately.

      Otherwise, if synchronously notify is false, queue a microtask to run finish notification steps for animation unless there is already a microtask queued to run those steps for animation.

  6. If current finished state is false and animation’s current finished promise is already resolved, set animation’s current finished promise to a new promise in the relevant Realm of animation.

Typically, notification about the finished state of an animation is performed asynchronously. This allows for the animation to temporarily enter the finished state without triggering events to be fired or promises to be resolved.

For example, in the following code fragment, animation temporarily enters the finished state. If notification of the finished state occurred synchronously this code would cause the finish event to be queued and the current finished promise to be resolved. However, if we reverse the order of the two statements such that the iterations is updated first, this would not happen. To avoid this surprising behavior, notification about the finished state of an animation is typically performed asynchronously.

var animation = elem.animate({ left: '100px' }, 2000);
animation.playbackRate = 2;
animation.currentTime = 1000; // animation is now finished
animation.effect.updateTiming({ iterations: 2 }); // animation is no longer finished

The one exception to this asynchronous behavior is when the finish an animation procedure is performed (typically by calling the finish() method). In this case the author’s intention to finish the animation is clear so the notification about the finished state of the animation occurs synchronously as demonstrated below.

var animation = elem.animate({ left: '100px' }, 1000);
animation.finish(); // finish event is queued immediately and finished promise
                    // is resolved despite the fact that the following statement
                    // causes the animation to leave the finished state
animation.currentTime = 0;

Note that like the procedure to finish an animation, the procedure to cancel an animation similarly queues the cancel event and rejects the current finished promise and current ready promise in a synchronous manner.

4.4.13. Finishing an animation

An animation can be advanced to the natural end of its current playback direction by using the procedure to finish an animation for animation defined below:

  1. If animation’s effective playback rate is zero, or if animation’s effective playback rate > 0 and associated effect end is infinity, throw an "InvalidStateError" DOMException and abort these steps.

  2. Apply any pending playback rate to animation.

  3. Set limit as follows:

    If playback rate > 0,

    Let limit be associated effect end.

    Otherwise,

    Let limit be zero.

  4. Silently set the current time to limit.

  5. If animation’s start time is unresolved and animation has an associated active timeline, let the start time be the result of evaluating timeline time - (limit / playback rate) where timeline time is the current time value of the associated timeline.

  6. If there is a pending pause task and start time is resolved,

    1. Let the hold time be unresolved.

      Typically the hold time will already be unresolved except in the case when the animation was previously idle.
    2. Cancel the pending pause task.

    3. Resolve the current ready promise of animation with animation.

  7. If there is a pending play task and start time is resolved, cancel that task and resolve the current ready promise of animation with animation.

  8. Run the procedure to update an animation’s finished state for animation with the did seek flag set to true, and the synchronously notify flag set to true.

4.4.14. Canceling an animation

An animation can be canceled which causes the current time to become unresolved hence removing any effects caused by the associated effect.

The procedure to cancel an animation for animation is as follows:

  1. If animation’s play state is not idle, perform the following steps:

    1. Run the procedure to reset an animation’s pending tasks on animation.

    2. Reject the current finished promise with a DOMException named "AbortError".

    3. Set the [[PromiseIsHandled]] internal slot of the current finished promise to true.

    4. Let current finished promise be a new promise in the relevant Realm of animation.

    5. Create an AnimationPlaybackEvent, cancelEvent.

    6. Set cancelEvent’s type attribute to cancel.

    7. Set cancelEvent’s currentTime to null.

    8. Let timeline time be the current time of the timeline with which animation is associated. If animation is not associated with an active timeline, let timeline time be n unresolved time value.

    9. Set cancelEvent’s timelineTime to timeline time. If timeline time is unresolved, set it to null.

    10. If animation has a document for timing, then append cancelEvent to its document for timing's pending animation event queue along with its target, animation. If animation is associated with an active timeline that defines a procedure to convert timeline times to origin-relative time, let the scheduled event time be the result of applying that procedure to timeline time. Otherwise, the scheduled event time is an unresolved time value.

      Otherwise, queue a task to dispatch cancelEvent at animation. The task source for this task is the DOM manipulation task source.

  2. Make animation’s hold time unresolved.

  3. Make animation’s start time unresolved.

4.4.15. Speed control

The rate of play of an animation can be controlled by setting its playback rate. For example, setting a playback rate of 2 will cause the animation’s current time to increase at twice the rate of its timeline. Similarly, a playback rate of -1 will cause the animation’s current time to decrease at the same rate as the time values from its timeline increase.

Animations have a playback rate that provides a scaling factor from the rate of change of the associated timeline’s time values to the animation’s current time. The playback rate is initially 1.

Setting an animation’s playback rate to zero effectively pauses the animation (however, the play state does not necessarily become paused).

4.4.15.1. Setting the playback rate of an animation

The procedure to set the playback rate of an animation, animation to new playback rate is as follows:

  1. Clear any pending playback rate on animation.

  2. Let previous time be the value of the current time of animation before changing the playback rate.

  3. Set the playback rate to new playback rate.

  4. If previous time is resolved, set the current time of animation to previous time

4.4.15.2. Seamlessly updating the playback rate of an animation

For an in-flight animation that is running on another process or thread, the procedure to set the playback rate may cause the animation to jump if the process or thread running the animation is not currently synchronized with the process or thread performing the update.

In order to produce seamless changes to the playback rate of an animation, animation’s may have a pending playback rate that defines a playback rate to be applied after any necessary synchronization has taken place (for the case of animations running in a different thread or process).

Initially the pending playback rate of an animation is unset.

The effective playback rate of an animation is its pending playback rate, if set, otherwise it is the animation’s playback rate.

When an animation, animation, is to apply any pending playback rate the following steps are performed:

  1. If animation does not have a pending playback rate, abort these steps.

  2. Set animation’s playback rate to its pending playback rate.

  3. Clear animation’s pending playback rate.

The procedure to seamlessly update the playback rate an animation, animation, to new playback rate preserving its current time is as follows:

  1. Let previous play state be animation’s play state.

    Note: It is necessary to record the play state before updating animation’s effective playback rate since, in the following logic, we want to immediately apply the pending playback rate of animation if it is currently finished regardless of whether or not it will still be finished after we apply the pending playback rate.

  2. Let animation’s pending playback rate be new playback rate.

  3. Perform the steps corresponding to the first matching condition from below:

    If animation has a pending play task or a pending pause task,

    Abort these steps.

    Note: The different types of pending tasks will apply the pending playback rate when they run so there is no further action required in this case.

    If previous play state is idle or paused, or animation’s current time is unresolved,

    Apply any pending playback rate on animation.

    Note: the second condition above is required so that if we have a running animation with an unresolved current time and no pending play task, we do not attempt to play it below.

    If previous play state is finished,
    1. Let the unconstrained current time be the result of calculating the current time of animation substituting an unresolved time value for the hold time.

    2. Let animation’s start time be the result of evaluating the following expression:

      timeline time - (unconstrained current time / pending playback rate)

      Where timeline time is the current time value of the timeline associated with animation.

      If pending playback rate is zero, let animation’s start time be timeline time.

    3. Apply any pending playback rate on animation.

    4. Run the procedure to update an animation’s finished state for animation with the did seek flag set to false, and the synchronously notify flag set to false.

    Otherwise,

    Run the procedure to play an animation for animation with the auto-rewind flag set to false.

4.4.16. Reversing an animation

The procedure to reverse an animation of animation animation is as follows:

  1. If there is no timeline associated with animation, or the associated timeline is inactive throw an "InvalidStateError" DOMException and abort these steps.

  2. Let original pending playback rate be animation’s pending playback rate.

  3. Let animation’s pending playback rate be the additive inverse of its effective playback rate (i.e. -effective playback rate).

  4. Run the steps to play an animation for animation with the auto-rewind flag set to true.

    If the steps to play an animation throw an exception, set animation’s pending playback rate to original pending playback rate and propagate the exception.

4.4.17. Play states

An animation may be described as being in one of the following play states for each of which, a non-normative description is also provided:

idle

The current time of the animation is unresolved and the start time of the animation is unresolved and there are no pending tasks. In this state the animation has no effect.

running

The animation has a resolved current time that changes on each animation frame (provided the playback rate is not zero and the timeline is active and monotonically increasing).

paused

The animation has been suspended and the current time is no longer changing.

finished

The animation has reached the natural boundary of its playback range and the current time is no longer updating.

The play state of animation, animation, at a given moment is the state corresponding to the first matching condition from the following:

All of the following conditions are true:

idle

Either of the following conditions are true:

paused

For animation, current time is resolved and either of the following conditions are true:

finished

Otherwise,

running

Note that the paused play state effectively "wins" over the finished play state.

However, an animation that is paused outside of its natural playback range can be converted from a paused animation into a finished animation without restarting by setting the start time such as below:

animation.effect.updateTiming({ duration: 5000 });
animation.currentTime = 4000;
animation.pause();
animation.ready.then(function() {
  animation.effect.updateTiming({ duration: 3000 });
  alert(animation.playState); // Displays 'paused'
  animation.startTime =
    document.timeline.currentTime - animation.currentTime * animation.playbackRate;
  alert(animation.playState); // Displays 'finished'
});

4.4.18. Animation events

Animation events include the animation playback events defined in this specification as well as the events from CSS transitions [CSS-TRANSITIONS-1] and events from CSS animations [CSS-ANIMATIONS-1]. Future specifications may extend this set with further types of animation events.

Each Document maintains a pending animation event queue that stores animation events along with their corresponding event targets and scheduled event time. The scheduled event time is a time value relative to the time origin representing when the event would ideally have been dispatched were animations updated at an infinitely high frequency. It is used by the procedure to update animations and send events to sort queued animation events chronologically. Note that this value may be unresolved if, for example, the animation's timeline produces values that are unrelated to the time origin (e.g. a timeline that tracks scroll-position) or if the timeline is inactive.

4.4.18.1. Sorting animation events

The following definitions are provided to assist with sorting queued events.

To convert an animation time to timeline time a time value, time, that is relative to the start time of an animation, animation, perform the following steps:

  1. If time is unresolved, return time.

  2. If time is infinity, return an unresolved time value.

  3. If animation’s playback rate is zero, return an unresolved time value.

  4. If animation’s start time is unresolved, return an unresolved time value.

  5. Return the result of calculating: time × (1 / playback rate) + start time (where playback rate and start time are the playback rate and start time of animation, respectively).

To convert a timeline time to an origin-relative time a time value, time, that is expressed in the same scale as the time values of a timeline, timeline, perform the following steps:

  1. Let timeline time be the result of converting time from an animation time to a timeline time.

  2. If timeline time is unresolved, return time.

  3. If animation is not associated with a timeline, return an unresolved time value.

  4. If animation is associated with an inactive timeline, return an unresolved time value.

  5. If there is no procedure to convert a timeline time to an origin-relative time for the timeline associated with animation, return an unresolved time value.

  6. Return the result of converting timeline time to an origin-relative time using the procedure defined for the timeline associated with animation.

4.4.18.2. Animation playback events

As animations play, they report changes to their status through animation playback events.

Animation playback events are a property of the timing model. As a result they are dispatched even when the associated effect of the animation is absent or has no observable result.

4.4.18.3. Types of animation playback events
finish

Queued whenever an animation enters the finished play state.

cancel

Queued whenever an animation enters the idle play state from another state. Creating a new animation that is initially idle does not generate a new cancel event.

remove

Queued whenever an animation is automatically removed. See § 5.5 Replacing animations.

4.5. Animation effects

An animation effect is an abstract term referring to an item in the timing hierarchy.

4.5.1. Relationship between animation effects and animations

The associated effect of an animation, if set, is a type of animation effect. The associated effect of an animation is said to be associated with that animation. At a given moment, an animation effect can be associated with at most one animation.

An animation effect, effect, is associated with a timeline, timeline, if effect is associated with an animation which, in turn, is associated with timeline.

4.5.2. Types of animation effects

This specification defines a single type of animation effect: keyframe effects. Subsequent levels of this specification will define further types of animation effects.

All types of animation effects define a number of common properties which are described in the following sections.

4.5.3. The active interval

The period that an animation effect is scheduled to run is called its active interval. Each animation effect has only one such interval.

The lower bound of the active interval typically corresponds to the start time of the animation associated with this animation effect but may be shifted by a start delay on the animation effect.

The upper bound of the interval is determined by the active duration.

The relationship between the start time, start delay, and active duration is illustrated below.

Examples of the effect of the start delay on the endpoints
          of the active interval
Examples of the effect of the start delay on the endpoints of the active interval.
(a) An animation effect with no delay; the start time and beginning of the active interval are coincident.
(b) An animation effect with a positive delay; the beginning of the active interval is deferred by the delay.
(c) An animation effect with a negative delay; the beginning of the active interval is brought forward by the delay.

An end delay may also be specified but is primarily only of use when sequencing animations.

Animation effects define an active interval which is the period of time during which the effect is scheduled to produce its effect with the exception of fill modes which apply outside the active interval.

The lower bound of the active interval is defined by the start delay.

The start delay of an animation effect is a signed offset from the start time of the animation with which the animation effect is associated.

The length of the active interval is called the active duration, the calculation of which is defined in § 4.8.2 Calculating the active duration.

Similar to the start delay, an animation effect also has an end delay which is primarily of use when sequencing animations based on the end time of another animation effect. Although this is typically only useful in combination with sequence effects which are introduced in a subsequent level of this specification, it is included here for the purpose of representing the min attribute in SVG ([SVG11], Chapter 19).

The end time of an animation effect is the result of evaluating max(start delay + active duration + end delay, 0).

4.5.4. Local time

The local time of an animation effect at a given moment is based on the first matching condition from the following:

If the animation effect is associated with an animation,

the local time is the current time of the animation.

Otherwise,

the local time is unresolved.

4.5.5. Animation effect phases and states

This section is non-normative

At a given moment, an animation effect may be in one of three possible phases. If an animation effect has an unresolved local time it will not be in any phase.

The different phases are illustrated below.

An example of the different phases and states used to
          describe an animation effect.
An example of the different phases and states used to describe an animation effect.

The phases are as follows:

before phase

The animation effect’s local time falls before the effect’s active interval and end time, or occurs during the range when a negative start delay is in effect.

active phase

The animation effect’s local time falls inside the effect’s active interval and outside the range of any negative start delay or negative end delay.

after phase

The animation effect’s local time falls after the effect’s active interval or after the end time if that comes first (due to a negative end delay), but not during the range when a negative start delay is in effect.

In addition to these phases, an animation effect may also be described as being in one of several overlapping states. These states are only established for the duration of a single animation frame and are primarily a convenience for describing stative parts of the model.

These states and their usage within the model are summarized as follows:

in play

Corresponds to an animation effect whose active time is changing on each frame.

current

Corresponds to an animation effect that is either in play or may become in play in the future based on its animation's current playback rate.

in effect

Corresponds to an animation effect that has a resolved active time. This occurs when either the animation effect is in its active phase or outside the active phase but at a time where the effect’s fill mode (see § 4.6 Fill behavior) causes its active time to be resolved. Only in effect animation effects apply a result to their target.

The normative definition of each of these states follows.

Determining the phase of an animation effect requires the following definitions:

animation direction

"backwards" if the effect is associated with an animation and the associated animation’s playback rate is less than zero; in all other cases, the animation direction is "forwards".

before-active boundary time

max(min(start delay, end time), 0)

active-after boundary time

max(min(start delay + active duration, end time), 0)

An animation effect is in the before phase if the animation effect’s local time is not unresolved and either of the following conditions are met:

  1. the local time is less than the before-active boundary time, or

  2. the animation direction is "backwards" and the local time is equal to the before-active boundary time.

An animation effect is in the after phase if the animation effect’s local time is not unresolved and either of the following conditions are met:

  1. the local time is greater than the active-after boundary time, or

  2. the animation direction is "forwards" and the local time is equal to the active-after boundary time.

An animation effect is in the active phase if the animation effect’s local time is not unresolved and it is not in either the before phase nor the after phase.

Furthermore, it is often convenient to refer to the case when an animation effect is in none of the above phases as being in the idle phase.

An animation effect is in play if all of the following conditions are met:

  1. the animation effect is in the active phase, and

  2. the animation effect is associated with an animation that is not finished.

An animation effect is current if any of the following conditions are true:

An animation effect is in effect if its active time, as calculated according to the procedure in § 4.8.3.1 Calculating the active time, is not unresolved.

4.6. Fill behavior

The effect of an animation effect when it is not in play is determined by its fill mode.

The possible fill modes are:

The normative definition of these modes is incorporated in the calculation of the active time in § 4.8.3.1 Calculating the active time.

Authors are discouraged from using fill modes to produce animations whose effect is applied indefinitely. Fill modes were introduced in order to represent the animation-fill-mode property defined by CSS animations [CSS-ANIMATIONS-1]. However, they produce situations where animation state would be accumulated indefinitely necessitating the automatic removal of animations defined in § 5.5 Replacing animations. Furthermore, indefinitely filling animations can cause changes to specified style to be ineffective long after all animations have completed since the animation style takes precedence in the CSS cascade [css-cascade-3].

Where possible, authors should prefer to set the final state of the animation directly in specified style. This can be achieved by waiting for the animation to finish and then updating the style as illustrated below:

// In the first frame after the following animation finishes, the callback for
// the `finished` promise will run BEFORE style is updated and hence will NOT
// flicker.
elem.animate({ transform: 'translateY(100px)' }, 200).finished(() => {
  elem.style.transform = 'translateY(100px)';
});

Alternatively, the author may set the specified style at the start of the animation and then animate from the original value as illustrated below:

elem.style.transform = 'translateY(100px)';
elem.animate({ transform: 'none', offset: 0 }, 200);

Complex effects involving layering many animations on top of one another may require temporary use of forwards fill modes to capture the final value of an animation before canceling it. For example:

elem.addEventListener('click', async evt => {
  const animation = elem.animate(
    { transform: `translate(${evt.clientX}px, ${evt.clientY}px)` },
    { duration: 800, fill: 'forwards' }
  );
  await animation.finished;
  // commitStyles will record the style up to and including `animation` and
  // update elem’s specified style with the result.
  animation.commitStyles();
  animation.cancel();
});

4.6.1. Fill modes

This section is non-normative

The effect of each fill mode is as follows:

none

The animation effect has no effect when it is not in play.

forwards

When the animation effect is in the after phase, the animation effect will produce the same iteration progress value as the last moment it is scheduled to be in play.

For all other times that the animation effect is not in play, it will have no effect.

backwards

When the animation effect is in the before phase, the animation effect will produce the same iteration progress value as the earliest moment that it is scheduled to be in play.

For all other times that the animation effect is not in play, it will have no effect.

both

When the animation effect is in its before phase, backwards fill behavior is used.

When the animation effect is in its after phase, forwards fill behavior is used.

Some examples of the these fill modes are illustrated below.

Examples of various fill modes and the states produced.
Examples of various fill modes and the states produced.
(a) fill mode "none". The animation effect has no effect outside its active phase.
(b) fill mode "forwards". After the active phase has finished, the iteration progress value continues to maintain a fill value.
(c) fill mode "backwards". The animation effect produces a fill value until the start of the active phase.
(d) fill mode "both". Both before and after the active phase the animation effect produces a fill value.

Note: setting a fill mode has no bearing on the endpoints of the active interval or the boundaries between phases. However, the fill mode does have an effect on various other properties of the timing model since the active time of an animation effect is only defined (that is, not unresolved) inside the active phase or when a fill is applied.

4.7. Repeating

4.7.1. Iteration intervals

It is possible to specify that an animation effect should repeat a fixed number of times or indefinitely. This repetition occurs within the active interval. The span of time during which a single repetition takes place is called an iteration interval.

Unlike the active interval, an animation effect can have multiple iteration intervals although typically only the interval corresponding to the current iteration is of interest.

The length of a single iteration is called the iteration duration. The initial iteration duration of an animation effect is zero.

This section is non-normative

Comparing the iteration duration and the active duration we have:

Iteration duration

The time taken for a single iteration of the animation effect to complete.

Active duration

The time taken for the entire animation effect to complete, including repetitions. This may be longer or shorter than the iteration duration.

The relationship between the iteration duration and active duration is illustrated below.

Comparison of the iteration duration and active time.
A comparison of the iteration duration and active duration of an animation effect with an iteration count of 2.5. Note that the iteration duration for the final iteration does not change, it is simply cut-off by the active duration.

4.7.2. Controlling iteration

The number of times an animation effect repeats is called its iteration count. The iteration count is a real number greater than or equal to zero. The iteration count may also be positive infinity to represent that the animation effect repeats indefinitely.

In addition to the iteration count, animation effects also have an iteration start property which specifies an offset into the series of iterations at which the animation effect should begin. The iteration start is a finite real number greater than or equal to zero.

The behavior of these parameters is defined in the calculations in § 4.8 Core animation effect calculations.

This section is non-normative

The effect of the iteration count and iteration start parameters is illustrated below.

The effect of the iteration count and iteration start parameters
The effect of the iteration count and iteration start parameters.
In the first case the iteration count is 2.5 resulting in the third iteration being cut-off half way through its iteration interval.
The second case is the same but with an iteration start of 0.5. This causes the animation effect to begin half way through the first iteration.

Unlike the iteration count parameter, the iteration start parameter does not effect the length of the active duration.

Note that values of iteration start greater than or equal to one are generally not useful unless used in combination with an animation effect that has an iteration composite operation of accumulate.

4.7.3. Iteration time space

This section is non-normative

In Web Animations all times are relative to some point of reference. These different points of reference produce different time spaces.

This can be compared to coordinate spaces as used in computer graphics. The zero time of a time space is analogous to the origin of a coordinate space.

We can describe animations that repeat as establishing a new time space each time the animation repeats: the iteration time space.

Iteration time space is a time space whose zero time is the beginning of an animation effect’s current iteration.

Within the Web Animations model we also refer to active time which is a time relative to the beginning of the active interval. This time space, however, is internal to the model and not exposed in the programming interface or in markup.

These time spaces are illustrated below.

A comparison of local time, active time, and iteration time.
A comparison of local time, active time, and iteration time for an animation with a iteration duration of 1s and an iteration count of 2.5.

Note: While the time spaces themselves are not bounded, Web Animations defines active time and the iteration progress such that they are clamped to a set range as shown in the diagram. For example, whilst a time of -1 second is a valid time in active time space, the procedure for calculating the active time defined in § 4.8.3.1 Calculating the active time will never return a negative value.

In addition to these time spaces we can also refer to the document time space which is time space of the time values of the default document timeline of the Document of the current global object.

4.7.4. Interval timing

This section is non-normative

When an animation effect repeats we must define the behavior at the iteration boundaries. For this, and indeed for all interval timing, Web Animations uses an endpoint-exclusive timing model. This means that whilst the begin time of an interval is included in the interval, the end time is not. In interval notation this can written [begin, end). This model provides sensible behavior when intervals are repeated and sequenced since there is no overlap between the intervals.

In the examples below, for the repeated effect, at local time 1s, the iteration time is 0. For the sequenced animations, at timeline time 1s, only animation B’s associated effect will be in play; there is no overlap.

Illustration of end-point exclusive timing.
Illustration of end-point exclusive timing. For both repeated and sequenced animation effects there is no overlap at the boundaries between intervals.

An exception to this behavior is that when performing a fill, if the fill begins at an interval endpoint, the endpoint is used. This behavior falls out of the algorithm given in § 4.8.3.3 Calculating the simple iteration progress and is illustrated below.

Effect of iterations and fill on iteration time.
After one iteration, the iteration progress is 0, but after two iterations (and there onwards), the iteration progress is 1 due to the special behavior defined when an animation effect fills.

4.8. Core animation effect calculations

4.8.1. Overview

This section is non-normative

At the core of the Web Animations timing model is the process that takes a local time value and converts it to an iteration progress.

The first step in this process is to calculate the bounds of the active interval which is determined by the active duration.

This process is illustrated below.

Calculation of the active duration.
Calculation of the active duration is based on multiplying the iteration duration by the iteration count.

The process for calculating the active duration is normatively defined in § 4.8.2 Calculating the active duration.

Having established the active duration, the process for transforming an animation effect’s local time into its transformed progress (iteration progress) is illustrated below.

An overview of timing model calculations.
An overview of timing model calculations.
(1) The local time is determined from the associated animation.
(2) The local time is converted into an active time by incorporating the start delay.
(3) The active time is divided by the iteration duration incorporating also the iteration start property to produce the overall progress.
(4) The overall progress time is then converted to an offset within a single iteration: the simple iteration progress.
(5) The simple iteration progress is converted into a directed progress by incorporating the playback direction.
(6) Finally, a timing function is applied to the directed progress to produce the transformed progress.

The first step, calculating the local time is described in § 4.5.4 Local time. Steps 2 to 4 in the diagram are described in the following sections. Steps 5 and 6 are described in § 4.9.1 Calculating the directed progress and § 4.10.1 Calculating the transformed progress respectively.

4.8.2. Calculating the active duration

The active duration is calculated as follows:

active duration = iteration duration × iteration count

If either the iteration duration or iteration count are zero, the active duration is zero.

This clarification is needed since the result of infinity multiplied by zero is undefined according to IEEE 754-2008.

4.8.3. Transforming the local time

4.8.3.1. Calculating the active time

The active time is based on the local time and start delay. However, it is only defined when the animation effect should produce an output and hence depends on its fill mode and phase as follows,

If the animation effect is in the before phase,

The result depends on the first matching condition from the following,

If the fill mode is backwards or both,

Return the result of evaluating max(local time - start delay, 0).

Otherwise,

Return an unresolved time value.

If the animation effect is in the active phase,

Return the result of evaluating local time - start delay.

If the animation effect is in the after phase,

The result depends on the first matching condition from the following,

If the fill mode is forwards or both,

Return the result of evaluating max(min(local time - start delay, active duration), 0).

Otherwise,

Return an unresolved time value.

Otherwise (the local time is unresolved),

Return an unresolved time value.

4.8.3.2. Calculating the overall progress

The overall progress describes the number of iterations that have completed (including partial iterations) and is defined as follows:

  1. If the active time is unresolved, return unresolved.

  2. Calculate an initial value for overall progress based on the first matching condition from below,

    If the iteration duration is zero,

    If the animation effect is in the before phase, let overall progress be zero, otherwise, let it be equal to the iteration count.

    Otherwise,

    Let overall progress be the result of calculating active time / iteration duration.

  3. Return the result of calculating overall progress + iteration start.

4.8.3.3. Calculating the simple iteration progress

The simple iteration progress is a fraction of the progress through the current iteration that ignores transformations to the time introduced by the playback direction or timing functions applied to the effect, and is calculated as follows:

  1. If the overall progress is unresolved, return unresolved.

  2. If overall progress is infinity, let the simple iteration progress be iteration start % 1.0, otherwise, let the simple iteration progress be overall progress % 1.0.

  3. If all of the following conditions are true,

    let the simple iteration progress be 1.0.

    The above step implements the behavior that when an animation’s active interval ends precisely at the end of an iteration, it fills by holding the endpoint of the final iteration rather than the start of the next iteration.

    The final condition prevents this from applying when we never played any iterations of the animation to begin with because the iteration count was zero.

  4. Return simple iteration progress.

4.8.4. Calculating the current iteration

The current iteration can be calculated using the following steps:

  1. If the active time is unresolved, return unresolved.

  2. If the animation effect is in the after phase and the iteration count is infinity, return infinity.

  3. If the simple iteration progress is 1.0, return floor(overall progress) - 1.

  4. Otherwise, return floor(overall progress).

4.9. Direction control

Animation effects may also be configured to run iterations in alternative directions using direction control. For this purpose, animation effects have a playback direction parameter which takes one of the following values:

The semantics of these values are incorporated into the calculation of the directed progress which follows.

This section is non-normative

A non-normative definition of these values is as follows:

normal

All iterations are played as specified.

reverse

All iterations are played in the reverse direction from the way they are specified.

alternate

Even iterations are played as specified, odd iterations are played in the reverse direction from the way they are specified.

alternate-reverse

Even iterations are played in the reverse direction from the way they are specified, odd iterations are played as specified.

4.9.1. Calculating the directed progress

The directed progress is calculated from the simple iteration progress using the following steps:

  1. If the simple iteration progress is unresolved, return unresolved.

  2. Calculate the current direction using the first matching condition from the following list:

    If playback direction is normal,

    Let the current direction be forwards.

    If playback direction is reverse,

    Let the current direction be reverse.

    Otherwise,
    1. Let d be the current iteration.

    2. If playback direction is alternate-reverse increment d by 1.

    3. If d % 2 == 0, let the current direction be forwards, otherwise let the current direction be reverse. If d is infinity, let the current direction be forwards.

  3. If the current direction is forwards then return the simple iteration progress.

    Otherwise, return 1.0 - simple iteration progress.

4.10. Time transformations

It is often desirable to control the rate at which an animation effect progresses. For example, easing the rate of animation can create a sense of momentum and produce a more natural effect. The CSS Easing Functions Module [CSS-EASING-1] defines timing functions for this purpose.

Animation effects have one timing function associated with them. The default timing function is the linear timing function.

4.10.1. Calculating the transformed progress

The transformed progress is calculated from the directed progress using the following steps:

  1. If the directed progress is unresolved, return unresolved.

  2. Calculate the value of the before flag as follows:

    1. Determine the current direction using the procedure defined in § 4.9.1 Calculating the directed progress.

    2. If the current direction is forwards, let going forwards be true, otherwise it is false.

    3. The before flag is set if the animation effect is in the before phase and going forwards is true; or if the animation effect is in the after phase and going forwards is false.

  3. Return the result of evaluating the animation effect’s timing function passing directed progress as the input progress value and before flag as the before flag.

4.11. The iteration progress

The iteration progress of an animation effect is simply its transformed progress.

5. Animation model

This section is non-normative

For some kinds of animation effects, the Web Animations animation model takes the iteration progress and current iteration values produced by the timing model and uses them to calculate a corresponding output.

The output of each such animation effect is then combined with that of others using an effect stack before being applied to the target properties (see § 5.4 Combining effects).

5.1. Introduction

An animation effect has zero or more associated properties that it affects in response to changes to its timing output. These properties are referred to as the effect’s target properties.

Given an iteration progress, a current iteration, and an underlying value, an animation effect produces an effect value for each animatable target property by applying the procedures from the animation type appropriate to the property.

5.2. Animating properties

Unless otherwise specified, all CSS properties are animatable. How property values combine is defined by the Animation type line in each property’s property definition table:

not animatable
The property is not animatable. It is not processed when listed in an animation keyframe, and is not affected by transitions.

Note: Properties are typically excluded from animation because animating them would create excessive complications. For example, properties defining animation parameters are not animatable since doing so would create complex recursive behavior.

Note: An animation effect that targets only properties that are not animatable will still exhibit the usual behavior for an animation effect such as firing events and delaying the fulfillment of the animation’s current finished promise.

discrete
The property’s values cannot be meaningfully combined, thus it is not additive and interpolation swaps from Va to Vb at 50% (p=0.5), i.e.
V result = V start if  p < 0.5 V end if  p 0.5
by computed value
Corresponding individual components of the computed values are combined (interpolated, added, or accumulated) using the indicated procedure for that value type (see CSS Values 4 § 3 Combining Values: Interpolation, Addition, and Accumulation). If the number of components or the types of corresponding components do not match, or if any component value uses discrete animation and the two corresponding values do not match, then the property values combine as discrete.
repeatable list
Same as by computed value except that if the two lists have differing numbers of items, they are first repeated to the least common multiple number of items. Each item is then combined by computed value. If a pair of values cannot be combined or if any component value uses discrete animation, then the property values combine as discrete.

Note: The repeatable list concept ensures that a list that is conceptually repeated to a certain length (as background-origin is repeated to the length of the background-image list) or repeated infinitely will smoothly transition between any values, and so that the computed value will properly represent the result (and potentially be inherited correctly).

(See prose)
Some properties have specific interpolation behavior not covered by the above cases; in this case the animation behavior will be specified explicitly for that property.

The animation type of properties that do not yet include an Animation type line in their property definition, is defined in Appendix A: Animation types of existing properties.

5.2.1. Custom Properties

For custom properties registered using the registerProperty() method for the current global object, the animation type is by computed value, derived from the type used in the property’s syntax definition. Where there is no computed value type that corresponds to the property’s specified syntax (e.g. when the syntax is the universal syntax definition) or when the custom property is not registered, the animation type is discrete.

5.3. Keyframe effects

Keyframe effects are a kind of animation effect that use the output of the timing model to update CSS properties of an element or pseudo-element (such as ::before or ::after [select]) referred to as the effect target.

In order for the effect target to have a well-defined lifecycle, it is represented as an Element known as the target element and a pseudo-element selector knows as the target pseudo-selector. If the effect target is an Element, the target element is that element and the target pseudo-selector is null. If the effect target is a pseudo-element, the target element is its originating element and the target pseudo-selector is as required to specify that particular pseudo-element.

Note that not all effect targets specified in this manner (such as ::part() pseudo-elements and unsupported pseudo-elements) have computed property values defined.

5.3.1. Keyframes

The effect values for a keyframe effect are calculated by interpolating between a series of property values positioned at fractional offsets. Each set of property values indexed by an offset is called a keyframe.

The offset of a keyframe is a value in the range [0, 1] or the special value null. The list of keyframes for a keyframe effect must be loosely sorted by offset which means that for each keyframe in the list that has a keyframe offset that is not null, the offset is greater than or equal to the offset of the previous keyframe in the list with a keyframe offset that is not null, if any.

The behavior when keyframes overlap or have unsupported values is defined in § 5.3.4 The effect value of a keyframe effect.

Each keyframe also has a timing function associated with it that is applied to the period of time between the keyframe on which it is specified and the next keyframe in the list. The timing function specified on the last keyframe in the list is never applied.

Each keyframe may have a keyframe-specific composite operation that, if set, is applied to all values specified in that keyframe. The possible operations and their meanings are identical to those defined for the composite operation associated with the keyframe effect as a whole in § 5.4.4 Effect composition. If the keyframe-specific composite operation for a keyframe is not set, the composite operation specified for the keyframe effect as a whole is used for values specified in that keyframe.

5.3.2. Computing property values

To compute a property value given a property property, a value value, and an Element element: resolve value according to the "Computed Value" line of the property’s definition table, using the computed values of element as the context for resolving dependencies, and return the result.

Note: The computed values on element are not affected by this algorithm.

This algorithm implies that property values specified in keyframes can establish order dependencies. When computing a property value, the computed values of dependencies held by value must be calculated first.

var animation = elem.animate([{ fontSize: '10px', width: '10em' },
                              { fontSize: '20px', width: '20em' }], 1000);
animation.currentTime = 500;
console.log(getComputedStyle(elem).fontSize); // Should be 15px
console.log(getComputedStyle(elem).width); // Should be 225px

In this example, in order to compute a property value for 10em, we must know the computed value of font-size on the target element, which in turn is determined by the effect value for font-size, which in turn requires that we compute property values for font-size. Hence, computing property values are subject to ordering constraints.

5.3.3. Calculating computed keyframes

Before calculating the effect value of a keyframe effect, the property values on its keyframes are computed, and the offset to use for any keyframes with a null keyframe offset is computed. The result of resolving these values is a set of computed keyframes.

The calculated keyframe offsets of a set of keyframe that includes suitable values for each null keyframe offset are referred to as the computed keyframe offsets.

To produce computed keyframe offsets, we define a procedure to compute missing keyframe offsets that takes a sequence of keyframes, keyframes, and has the following steps:

  1. For each keyframe, in keyframes, let the computed keyframe offset of the keyframe be equal to its keyframe offset value.

  2. If keyframes contains more than one keyframe and the computed keyframe offset of the first keyframe in keyframes is null, set the computed keyframe offset of the first keyframe to 0.

  3. If the computed keyframe offset of the last keyframe in keyframes is null, set its computed keyframe offset to 1.

  4. For each pair of keyframes A and B where:

    calculate the computed keyframe offset of each keyframe between A and B as follows:

    1. Let offsetk be the computed keyframe offset of a keyframe k.

    2. Let n be the number of keyframes between and including A and B minus 1.

    3. Let index refer to the position of keyframe in the sequence of keyframes between A and B such that the first keyframe after A has an index of 1.

    4. Set the computed keyframe offset of keyframe to offsetA + (offsetBoffsetA) × index / n.

Computed keyframes are produced using the following procedure. Note that this procedure is only performed on a keyframe effect having an effect target for which computed property values can be calculated.

  1. Let computed keyframes be an empty list of keyframes.

  2. For each keyframe in the list of keyframes specified on this keyframe effect, perform the following steps:

    1. Add a new empty keyframe, computed keyframe, to computed keyframes.

    2. For each property specified in keyframe:

      For example, if keyframe has a value of "12pt" for the border-width property, the user agent may compute a property value of "16px" for each of the longhand properties: border-bottom-width, border-left-width, border-right-width, and border-top-width. As a result, computed keyframe would not have a value for the border-width property, but would instead include each of the longhand properties, and each with the value "16px".

      If conflicts arise when expanding shorthand properties or replacing logical properties with physical properties, apply the following rules in order until the conflict is resolved:

      1. Longhand properties override shorthand properties (e.g. border-top-color overrides border-top).

      2. Shorthand properties with fewer longhand components override those with more longhand components (e.g. border-top overrides border-color).

      3. Physical properties override logical properties.

      4. For shorthand properties with an equal number of longhand components, properties whose IDL name (see the CSS property to IDL attribute algorithm [CSSOM]) appears earlier when sorted in ascending order by the Unicode codepoints that make up each IDL name, override those who appear later.

  3. Apply the procedure to compute missing keyframe offsets to computed keyframes.

  4. Return computed keyframes.

5.3.4. The effect value of a keyframe effect

The effect value of a single property referenced by a keyframe effect as one of its target properties, for a given iteration progress, current iteration and underlying value is calculated as follows.

  1. If iteration progress is unresolved abort this procedure.

  2. Let target property be the longhand property for which the effect value is to be calculated.

  3. If animation type of the target property is not animatable abort this procedure since the effect cannot be applied.

  4. If the keyframe effect does not have an effect target, or if the effect target cannot have computed property values calculated, abort this procedure.

  5. Define the neutral value for composition as a value which, when combined with an underlying value using the add composite operation, produces the underlying value.

  6. Let property-specific keyframes be the result of getting the set of computed keyframes for this keyframe effect.

  7. Remove any keyframes from property-specific keyframes that do not have a property value for target property.

  8. If property-specific keyframes is empty, return underlying value.

  9. If there is no keyframe in property-specific keyframes with a computed keyframe offset of 0, create a new keyframe with a computed keyframe offset of 0, a property value set to the neutral value for composition, and a composite operation of add, and prepend it to the beginning of property-specific keyframes.

  10. Similarly, if there is no keyframe in property-specific keyframes with a computed keyframe offset of 1, create a new keyframe with a computed keyframe offset of 1, a property value set to the neutral value for composition, and a composite operation of add, and append it to the end of property-specific keyframes.

  11. Let interval endpoints be an empty sequence of keyframes.

  12. Populate interval endpoints by following the steps from the first matching condition from below:

    If iteration progress < 0 and there is more than one keyframe in property-specific keyframes with a computed keyframe offset of 0,

    Add the first keyframe in property-specific keyframes to interval endpoints.

    If iteration progress ≥ 1 and there is more than one keyframe in property-specific keyframes with a computed keyframe offset of 1,

    Add the last keyframe in property-specific keyframes to interval endpoints.

    Otherwise,
    1. Append to interval endpoints the last keyframe in property-specific keyframes whose computed keyframe offset is less than or equal to iteration progress and less than 1. If there is no such keyframe (because, for example, the iteration progress is negative), add the last keyframe whose computed keyframe offset is 0.

    2. Append to interval endpoints the next keyframe in property-specific keyframes after the one added in the previous step.

  13. For each keyframe in interval endpoints:

    1. If keyframe has a composite operation that is not replace, or keyframe has no composite operation and the composite operation of this keyframe effect is not replace, then perform the following steps:

      1. Let composite operation to use be the composite operation of keyframe, or if it has none, the composite operation of this keyframe effect.

      2. Let value to combine be the property value of target property specified on keyframe.

      3. Replace the property value of target property on keyframe with the result of combining underlying value (Va) and value to combine (Vb) using the procedure for the composite operation to use corresponding to the target property’s animation type.

  14. If there is only one keyframe in interval endpoints return the property value of target property on that keyframe.

  15. Let start offset be the computed keyframe offset of the first keyframe in interval endpoints.

  16. Let end offset be the computed keyframe offset of last keyframe in interval endpoints.

  17. Let interval distance be the result of evaluating (iteration progress - start offset) / (end offset - start offset).

  18. Let transformed distance be the result of evaluating the timing function associated with the first keyframe in interval endpoints passing interval distance as the input progress.

  19. Return the result of applying the interpolation procedure defined by the animation type of the target property, to the values of the target property specified on the two keyframes in interval endpoints taking the first such value as Vstart and the second as Vend and using transformed distance as the interpolation parameter p.

Note that this procedure assumes the following about the list of keyframes specified on the effect:

It is the responsibility of the user of the model (for example, a declarative markup or programming interface) to ensure these conditions are met.

For example, for the programming interface defined by this specification, these conditions are met by the procedure to produce the computed keyframes that become the input to this procedure.

Note: this procedure permits overlapping keyframes. The behavior is that at the point of overlap the output value jumps to the value of the last defined keyframe at that offset. For overlapping keyframes at 0 or 1, the output value for iteration progress values less than 0 or greater than or equal to 1 is the value of the first keyframe or the last keyframe in keyframes respectively.

Note that computed keyframes are "live": user-agents must behave as if they are recreated every time the effect value is calculated.

For example, if there is an ongoing transition on the font-size property from 10px to 20px, a property value specified as 1em in a keyframe would during keyframe computation resolve against the computed value in the range [10px, 20px] produced by the transition on font-size.

In the presence of certain timing functions, the input iteration progress to an animation effect is not limited to the range [0, 1]. Currently, however, keyframe offsets are limited to the range [0, 1] and property values are simply extrapolated for input iteration progress values outside this range.

We have considered removing this restriction since some cases exist where it is useful to be able to specify non-linear changes in property values at iteration progress values outside the range [0, 1]. One example is an animation that interpolates from green to yellow but has an overshoot timing function that makes it temporarily interpolate "beyond" yellow to red before settling back to yellow.

While this effect could be achieved by modification of the keyframes and timing function, this approach seems to break the model’s separation of timing concerns from animation effects.

It is not clear how this effect should be achieved but we note that allowing keyframe offsets outside [0, 1] may make the currently specified behavior where keyframes at offset 0 and 1 are synthesized as necessary, inconsistent.

See section 4 (Keyframe offsets outside [0, 1]) of minuted discussion from Tokyo 2013 F2F.

<https://github.com/w3c/csswg-drafts/issues/2081>

5.4. Combining effects

This section is non-normative

After calculating the effect values for a keyframe effect, they are applied to the animation effect’s target properties.

Since it is possible for multiple in effect keyframe effects to target the same property it is often necessary to combine the results of several keyframe effects together. This process is called compositing and is based on establishing an effect stack for each property targeted by an in effect animation effect.

After compositing the results of keyframe effects together, the composited result is combined with other values specified for the target property.

The arrangement is illustrated below:

Overview of the application of effect values to their target properties
Overview of the application of effect values to their target properties.
The results of keyframe effects targeting the same property are composited together using an effect stack.
The result of this composition is then inserted into the CSS cascade at an appropriate point.

For the first part of this operation—combining effect values that target the same property— it is necessary to determine both how keyframe effects are combined with one another, as well as the order in which they are applied, that is, their relative composite order.

The matter of how effect values are combined is governed by the composite operation of the corresponding keyframe effects.

The relative composite order of effect values is determined by an effect stack established for each animated property.

5.4.1. Animation classes

This specification provides a common animation model intended to be used by other specifications that define markup or programming interfaces on top of this model. The particular markup or programming interface that generated an animation defines its animation class.

Further specifications may define specialized behavior for composite ordering between different classes of animations or within a particular class.

This section is non-normative

For example, animations whose class is "CSS animation" are defined as having a higher composite order than animations whose class is "CSS transition" but lower than other animations without a specific class.

Within the set of "CSS animation" objects, specialized composite ordering is defined based on the animation-name property amongst other factors.

5.4.2. The effect stack

Associated with each property targeted by one or more keyframe effects is an effect stack that establishes the relative composite order of the keyframe effects.

The relative composite order of any two keyframe effects, A and B, within an effect stack is established by comparing their properties as follows:

  1. Let the associated animation of an animation effect be the animation associated with the animation effect that affecting the property with which this effect stack is associated.

  2. Sort A and B by applying the following conditions in turn until the order is resolved,

    1. If A and B’s associated animations differ by class, sort by any inter-class composite order defined for the corresponding classes.

    2. If A and B are still not sorted, sort by any class-specific composite order defined by the common class of A and B’s associated animations.

    3. If A and B are still not sorted, sort by their corresponding position in the global animation list.

Animation effects that sort earlier have lower composite order.

5.4.3. Calculating the result of an effect stack

In order to calculate the final value of an effect stack, the effect values of each keyframe effect in the stack are combined in composite order.

Each step in the process of evaluating an effect stack takes an underlying value as input.

For each keyframe effect in the stack, the appropriate effect value from the keyframe effect is combined with the underlying value to produce a new value. This resulting value becomes the underlying value for combining the next keyframe effect in the stack.

The final value of an effect stack, called the composited value, is simply the result of combining the effect value of the final (highest composite order) keyframe effect in the stack with the underlying value at that point.

5.4.4. Effect composition

The specific operation used to combine an effect value with an underlying value is determined by the composite operation of the keyframe effect that produced the effect value.

This specification defines three composite operations as follows:

replace

The result of compositing the effect value with the underlying value is simply the effect value.

add

The effect value is added to the underlying value. For animation types where the addition operation is defined such that it is not commutative, the order of the operands is underlying value + effect value.

accumulate

The effect value is accumulated onto the underlying value. For animation types where the accumulation operation is defined such that it is not commutative, the order of the operands is underlying value followed by effect value.

5.4.5. Applying the composited result

Applying a composited value to a target property is achieved by adding a specified value to the CSS cascade.

The level of the cascade to which this specified value is added depends on the class of the animation associated with the effect with the highest composite order in the effect stack for a given property. By default, the specified value is added to the "Animation declarations" level of the cascade ([css-cascade-3]).

This section is non-normative

For example, if the effect with the highest composite order is associated with a "CSS transition"-class animation, the composited value will be added to "Transition declarations" level of the cascade.

The composited value calculated for a CSS target property is applied using the following process.

  1. Calculate the base value of the property as the value generated for that property by computing the computed value for that property in the absence of animations.

  2. Establish the effect stack for the property (see § 5.4.2 The effect stack).

  3. Calculate the composited value of the effect stack passing in the base value of the property as the initial underlying value (see § 5.4.3 Calculating the result of an effect stack).

  4. Insert the composited value into the CSS cascade at the level defined for the class of the animation associated with the effect at the top of the effect stack established for the target property.

5.5. Replacing animations

This section is non-normative

Using the programming interface defined in this specification, it is possible to repeatedly trigger new animations that contribute to an element’s animated style indefinitely.

For example, consider the following code:

elem.addEventListener('mousemove', evt => {
  circle.animate(
    { transform: `translate(${evt.clientX}px, ${evt.clientY}px)` },
    { duration: 500, fill: 'forwards' }
  );
});

This will generate a new forwards-filling animation each time the mouse is moved, quickly producing hundreds, even thousands of forwards-filling animations.

If the user agent is required to retain all such animations, the list of animations would grow in an unbounded fashion, producing a memory leak.

This section defines a mechanism that causes overridden animations to be automatically removed unless the author explicitly requests they be retained.

5.5.1. Replace state

An animation maintains a replace state that may be one of the following values:

The initial value of an animation's replace state is active.

The animation effects of an animation whose replace state is removed are not included in the effect stacks of their target properties.

5.5.2. Removing replaced animations

An animation is replaceable if all of the following conditions are true:

When asked to remove replaced animations for a Document, doc, then for every animation, animation, that:

perform the following steps:

  1. Set animation’s replace state to removed.

  2. Create an AnimationPlaybackEvent, removeEvent.

  3. Set removeEvent’s type attribute to remove.

  4. Set removeEvent’s currentTime attribute to the current time of animation.

  5. Set removeEvent’s timelineTime attribute to the current time of the timeline with which animation is associated.

  6. If animation has a document for timing, then append removeEvent to its document for timing's pending animation event queue along with its target, animation. For the scheduled event time, use the result of applying the procedure to convert timeline time to origin-relative time to the current time of the timeline with which animation is associated.

    Otherwise, queue a task to dispatch removeEvent at animation. The task source for this task is the DOM manipulation task source.

5.6. Side effects of animation

For every property targeted by at least one animation effect that is current or in effect, and which is associated with an animation whose replace state is not removed, the user agent must act as if the will-change property ([css-will-change-1]) on the effect target includes the property.

This section is non-normative

As a result of the above requirement, if an animation targets, for example, the transform property of an element, a stacking context will be created for the effect target so long as the animation is in the before phase, the active phase or, if it has a fill mode of "forwards" or "both", the after phase.

6. Programming interface

This section is non-normative

In addition to the abstract model described above, Web Animations also defines a programming interface to the model. This interface can be used to inspect and extend animations produced by declarative means or for directly producing animations when a procedural approach is more suitable.

6.1. Time values in the programming interface

Time values are represented in the programming interface with the type double. Unresolved time values are represented by the value null.

6.2. The AnimationTimeline interface

Timelines are represented in the Web Animations API by the AnimationTimeline interface.

[Exposed=Window]
interface AnimationTimeline {
    readonly attribute double? currentTime;
};
currentTime, of type double, readonly, nullable

Returns the current time for this timeline or null if this timeline is inactive.

6.3. The DocumentTimeline interface

Document timelines, including the default document timeline, are represented in the Web Animations API by the DocumentTimeline interface.

dictionary DocumentTimelineOptions {
  DOMHighResTimeStamp originTime = 0;
};

[Exposed=Window]
interface DocumentTimeline : AnimationTimeline {
  constructor(optional DocumentTimelineOptions options = {});
};
originTime, of type DOMHighResTimeStamp, defaulting to 0

The origin time for the timeline specified as a real number of milliseconds relative to the time origin.

DocumentTimeline (options)

Creates a new DocumentTimeline. The Document with which the timeline is associated is the Document associated with the Window that is the current global object.

options

Configuration parameters for the newly-created timeline. This specification defines only the originTime member but other specifications may extend this set.

6.4. The Animation interface

Animations are represented in the Web Animations API by the Animation interface.

[Exposed=Window]
interface Animation : EventTarget {
    constructor(optional AnimationEffect? effect = null,
                optional AnimationTimeline? timeline);
             attribute DOMString                id;
             attribute AnimationEffect?         effect;
             attribute AnimationTimeline?       timeline;
             attribute double?                  startTime;
             attribute double?                  currentTime;
             attribute double                   playbackRate;
    readonly attribute AnimationPlayState       playState;
    readonly attribute AnimationReplaceState    replaceState;
    readonly attribute boolean                  pending;
    readonly attribute Promise<Animation>       ready;
    readonly attribute Promise<Animation>       finished;
             attribute EventHandler             onfinish;
             attribute EventHandler             oncancel;
             attribute EventHandler             onremove;
    undefined cancel();
    undefined finish();
    undefined play();
    undefined pause();
    undefined updatePlaybackRate(double playbackRate);
    undefined reverse();
    undefined persist();
    [CEReactions]
    undefined commitStyles();
};
Animation (effect, timeline)

Creates a new Animation object using the following procedure.

  1. Let animation be a new Animation object.

  2. Run the procedure to set the timeline of an animation on animation passing timeline as the new timeline or, if a timeline argument is missing, passing the default document timeline of the Document associated with the Window that is the current global object.

  3. Run the procedure to set the associated effect of an animation on animation passing source as the new effect.

effect

An optional value which, if not null, specifies the associated effect to assign to the newly created animation.

timeline

An optional value which, if present, specifies the timeline with which to associate the newly-created animation. If missing, the default document timeline of the Document associated with the Window that is the current global object is used.

id, of type DOMString

A string used to identify the animation.

effect, of type AnimationEffect, nullable

The associated effect of this animation. Setting this attribute updates the object’s associated effect using the procedure to set the associated effect of an animation.

timeline, of type AnimationTimeline, nullable

The timeline associated with this animation. Setting this attribute updates the object’s timeline using the procedure to set the timeline of an animation.

startTime, of type double, nullable

Returns the start time of this animation. Setting this attribute updates the start time using the procedure to set the start time of this object to the new value.

currentTime, of type double, nullable

The current time of this animation. Setting this attribute follows the procedure to set the current time of this object to the new value.

playbackRate, of type double

The playback rate of this animation. Setting this attribute follows the procedure to set the playback rate of this object to the new value.

Setting this attribute performs a synchronous update to the playback rate meaning that it does not make any attempt to synchronize with the playback state of animations running on a separate process or thread. As a result, setting the playbackRate for an in-flight animation may cause it to jump.

To set the playback rate for an in-flight animation such that it smoothly updates, use the asynchronous updatePlaybackRate() method.

playState, of type AnimationPlayState, readonly

The play state of this animation.

replaceState, of type AnimationReplaceState, readonly

The replace state of this animation.

pending, of type boolean, readonly

Returns true if this animation has a pending play task or a pending pause task.

ready, of type Promise<Animation>, readonly

Returns the current ready promise for this object.

finished, of type Promise<Animation>, readonly

Returns the current finished promise for this object.

onfinish, of type EventHandler

The event handler for the finish event.

oncancel, of type EventHandler

The event handler for the cancel event.

onremove, of type EventHandler

The event handler for the remove event.

void cancel()

Clears all effects caused by this animation and aborts its playback by running the cancel an animation procedure for this object.

void finish()

Seeks the animation to the associated effect end in the current direction by running the finish an animation procedure for this object.

DOMException of type InvalidStateError

Raised if this animation’s playback rate is zero, or if this animation’s playback rate is > zero and the associated effect end is infinity.

void play()

Begins or resumes playback of the animation by running the procedure to play an animation passing true as the value of the auto-rewind flag.

void pause()

Suspends the playback of this animation by running the procedure to pause an animation for this object.

void updatePlaybackRate(playbackRate)

Performs an asynchronous update of the playback rate of this animation by performing the seamlessly update the playback rate procedure, passing playbackRate as the new playback rate.

playbackRate

A finite real number specifying the updated playback rate to use.

void reverse()

Inverts the playback rate of this animation and plays it using the reverse an animation procedure for this object. As with play(), this method unpauses the animation and, if the animation has already finished playing in the reversed direction, seeks to the start of the associated effect.

void persist()

Sets this animation’s replace state to persisted.

void commitStyles()

Writes the current effect values produced by this animation’s animation effects to their corresponding effect targets' inline style using the commit computed styles procedure.

Unlike most other methods defined on this interface, calling this method does trigger a style change event (see § 6.13 Model liveness).

Since the procedure to commit computed styles includes the effect values for the animation even if it is removed, this method is useful for retaining the effect of an animation after it has been replaced (see § 5.5.2 Removing replaced animations) without retaining the actual animation.

Note that the values committed are the computed values produced by the animation effects at the time when this method is called. Since these values are computed values, they do not reflect to changes to context such as responding to changes to CSS variables or recalculating em units based on changes to the computed font-size in the way the values produced by a live animation would.

In order to retain full fidelity of a filling animation’s result after it has been replaced (see § 5.5 Replacing animations), the persist() method may be used, but note that doing so will mean the animation continues to consume resources.

To commit computed styles for an animation, animation:

  1. Let targets be the set of all effect targets for animation effects associated with animation.

  2. For each target in targets:

    1. If target is not an element capable of having a style attribute [CSS-STYLE-ATTR] (for example, it is a pseudo-element or is an element in a document format for which style attributes are not defined) throw a "NoModificationAllowedError" DOMException and abort these steps.

    2. If, after applying any pending style changes, target is not being rendered, throw an "InvalidStateError" DOMException and abort these steps.

      The definition of being rendered [HTML] with regards to display: contents is still under discussion. For the purpose of this procedure, we assume that an element with display: contents that otherwise would have associated layout boxes (i.e. it is connected and not part of a display: none subtree) is being rendered.

    3. Let inline style be the result of getting the CSS declaration block corresponding to target’s style attribute. If target does not have a style attribute, let inline style be a new empty CSS declaration block with the owner node set to target.

    4. Let targeted properties be the set of physical longhand properties that are a target property for at least one animation effect associated with animation whose effect target is target.

    5. For each property, property, in targeted properties:

      1. Let partialEffectStack be a copy of the effect stack for property on target.

      2. If animation’s replace state is removed, add all animation effects associated with animation whose effect target is target and which include property as a target property to partialEffectStack.

      3. Remove from partialEffectStack any animation effects whose associated animation has a higher composite order than animation.

      4. Let effect value be the result of calculating the result of partialEffectStack for property using target’s computed style (see § 5.4.3 Calculating the result of an effect stack).

      5. Set a CSS declaration property for effect value in inline style.

    6. Update style attribute for inline style.

6.4.1. The AnimationPlayState enumeration

enum AnimationPlayState { "idle", "running", "paused", "finished" };
idle

Corresponds to the idle play state.

running

Corresponds to the running play state.

paused

Corresponds to the paused play state.

finished

Corresponds to the finished play state.

6.4.2. The AnimationReplaceState enumeration

enum AnimationReplaceState { "active", "removed", "persisted" };
active

Corresponds to the active replace state.

removed

Corresponds to the removed replace state.

persisted

Corresponds to the persisted replace state.

6.5. The AnimationEffect interface

Animation effects are represented in the Web Animations API by the abstract AnimationEffect interface.

[Exposed=Window]
interface AnimationEffect {
    EffectTiming         getTiming();
    ComputedEffectTiming getComputedTiming();
    undefined            updateTiming(optional OptionalEffectTiming timing = {});
};
In future, we may expose any onupdate (double? progress, double currentIteration, Animatable? target, any underlyingValue) so that the animation effects can be driven apart from the timing model.
getTiming()

Returns the specified timing properties for this animation effect.

For the correspondence between the members of the returned EffectTiming object and properties of the timing model, see the the EffectTiming interface.

getComputedTiming()

Returns the calculated timing properties for this animation effect.

Although some of the attributes of the object returned by getTiming() and getComputedTiming() are common, their values may differ in the following ways:

Note: It is likely that other timing members may be extended in future to include auto-like values. When performing timing calculations, authors are encouraged to use getComputedTiming() where possible to avoid incompatibility should the range or type of allowed specified values be changed.

In addition to possible differences in the values returned, compared to getTiming(), getComputedTiming() returns additional timing information as defined by the ComputedEffectTiming dictionary.

updateTiming(timing)

Updates the specified timing properties of this animation effect by performing the procedure to update the timing properties of an animation effect passing the timing parameter as input.

optional OptionalEffectTiming timing

The timing properties to update. The timing properties corresponding to any members not present on timing will not be modified.

The remove() method can be used to remove an effect from either its parent group or animation. Should we keep it in level 1 and define it simply as removing the animation effect from its animation? [Issue #2082]

6.5.1. The EffectTiming and OptionalEffectTiming dictionaries

The EffectTiming dictionary represents the timing properties of an AnimationEffect.

The OptionalEffectTiming dictionary is a variant of the EffectTiming dictionary that allows some members to be not present. This is used by the updateTiming() method of the AnimationEffect interface to perform a delta update to the timing properties of an animation effect.

dictionary EffectTiming {
    double                             delay = 0;
    double                             endDelay = 0;
    FillMode                           fill = "auto";
    double                             iterationStart = 0.0;
    unrestricted double                iterations = 1.0;
    (unrestricted double or DOMString) duration = "auto";
    PlaybackDirection                  direction = "normal";
    DOMString                          easing = "linear";
};

dictionary OptionalEffectTiming {
    double                             delay;
    double                             endDelay;
    FillMode                           fill;
    double                             iterationStart;
    unrestricted double                iterations;
    (unrestricted double or DOMString) duration;
    PlaybackDirection                  direction;
    DOMString                          easing;
};
delay, of type double, defaulting to 0

The start delay which represents the number of milliseconds from the start time of the associated animation to the start of the active interval.

endDelay, of type double, defaulting to 0

The end delay which represents the number of milliseconds from the end of an animation effect’s active interval until its end time.

fill, of type FillMode, defaulting to "auto"

The fill mode which defines the behavior of the animation effect outside its active interval.

When performing timing calculations the special string value auto is expanded to one of the fill modes recognized by the timing model as follows,

If the animation effect to which the fill mode is being is applied is a keyframe effect,

Use none as the fill mode.

Otherwise,

Use both as the fill mode.

As described in § 4.6 Fill behavior, authors are discouraged from using indefinitely filling animations.
iterationStart, of type double, defaulting to 0.0

The animation effect’s iteration start property which is a finite real number greater than or equal to zero representing the iteration index at which the animation effect begins and its progress through that iteration.

For example, a value of 0.5 indicates that the animation effect begins half way through its first iteration. A value of 1.2 indicates the animation effect begins 20% of the way through its second iteration.

Note that the value of iterations is effectively added to the iterationStart such that an animation effect with an iterationStart of "0.5" and iterations of "2" will still repeat twice however it will begin and end half-way through its iteration interval.

iterationStart values greater than or equal to one are typically only useful in combination with an animation effect that has an iteration composite operation of accumulate or when the current iteration index is otherwise significant.

iterations, of type unrestricted double, defaulting to 1.0

The animation effect’s iteration count property which is a real number greater than or equal to zero (including positive infinity) representing the number of times to the animation effect repeats.

This may be set to +Infinity to cause the animation effect to repeat forever (unless the duration of the effect is zero, in which case it will finish immediately).

duration, of type (unrestricted double or DOMString), defaulting to "auto"

The iteration duration which is a real number greater than or equal to zero (including positive infinity) representing the time taken to complete a single iteration of the animation effect.

In this level of this specification, the string value auto is treated as the value zero for the purpose of timing model calculations and for the result of the duration member returned from getComputedTiming(). If the author specifies the auto value user agents must, however, return auto for the duration member returned from getTiming().

This is a forwards-compatibility measure since a future level of this specification is expected to introduce group effects where the auto value expands to include the duration of the child effects.

direction, of type PlaybackDirection, defaulting to "normal"

The playback direction of the animation effect which defines whether playback proceeds forwards, backwards, or alternates on each iteration.

easing, of type DOMString, defaulting to "linear"

The timing function used to scale the time to produce easing effects.

The syntax of the string is defined by the <easing-function> production [CSS-EASING-1].

6.5.2. The FillMode enumeration

enum FillMode { "none", "forwards", "backwards", "both", "auto" };
none

No fill.

forwards

Fill forwards.

backwards

Fill backwards.

both

Fill backwards and forwards.

auto

No fill. In a subsequent level of this specification, this may produce different behavior for other types of animation effects.

6.5.3. The PlaybackDirection enumeration

enum PlaybackDirection { "normal", "reverse", "alternate", "alternate-reverse" };
normal

All iterations are played as specified.

reverse

All iterations are played in the reverse direction from the order they are specified.

alternate

Even iterations are played as specified, odd iterations are played in the reverse direction from the order they are specified.

alternate-reverse

Even iterations are played in the reverse direction from the order they are specified, odd iterations are played as specified.

6.5.4. Updating the timing of an AnimationEffect

To update the timing properties of an animation effect, effect, from an EffectTiming or OptionalEffectTiming object, input, perform the following steps:

  1. If the iterationStart member of input is present and less than zero, throw a TypeError and abort this procedure.

    Note: The reason for using a TypeError rather than a RangeError is to mirror the behavior of WebIDL’s [EnforceRange] annotation should that annotation be able to be used with floating-point values in the future.

  2. If the iterations member of input is present, and less than zero or is the value NaN, throw a TypeError and abort this procedure.

  3. If the duration member of input is present, and less than zero or is the value NaN, throw a TypeError and abort this procedure.

  4. If the easing member of input is present but cannot be parsed using the <easing-function> production [CSS-EASING-1], throw a TypeError and abort this procedure.

  5. Assign each member present in input to the corresponding timing property of effect as follows:

6.5.5. The ComputedEffectTiming dictionary

Timing properties calculated by the timing model are exposed using ComputedEffectTiming dictionary objects.

dictionary ComputedEffectTiming : EffectTiming {
    unrestricted double  endTime;
    unrestricted double  activeDuration;
    double?              localTime;
    double?              progress;
    unrestricted double? currentIteration;
};
endTime, of type unrestricted double

The end time of the animation effect expressed in milliseconds since zero local time (that is, since the associated animation’s start time if this animation effect is associated with an animation). This corresponds to the end of the animation effect’s active interval plus any end delay.

activeDuration, of type unrestricted double

The active duration of this animation effect.

localTime, of type double, nullable

The local time of this animation effect.

This will be null if this animation effect is not associated with an animation.

progress, of type double, nullable

The current iteration progress of this animation effect.

currentIteration, of type unrestricted double, nullable

The current iteration index beginning with zero for the first iteration.

In most cases this will be a (positive) integer. However, for a zero-duration animation that repeats infinite times, the value will be positive Infinity.

As with unresolved times, an unresolved current iteration is represented by a null value.

6.6. The KeyframeEffect interface

Keyframe effects are represented by the KeyframeEffect interface.

[Exposed=Window]
interface KeyframeEffect : AnimationEffect {
    constructor(Element? target,
                object? keyframes,
                optional (unrestricted double or KeyframeEffectOptions) options = {});
    constructor(KeyframeEffect source);
    attribute Element?           target;
    attribute CSSOMString?       pseudoElement;
    attribute CompositeOperation composite;
    sequence<object> getKeyframes();
    undefined        setKeyframes(object? keyframes);
};
KeyframeEffect (target, keyframes, options)

Creates a new KeyframeEffect object using the following procedure:

  1. Create a new KeyframeEffect object, effect.

  2. Set the target element of effect to target.

  3. Set the target pseudo-selector to the result corresponding to the first matching condition from below.

    If options is a KeyframeEffectOptions object with a pseudoElement property,

    Set the target pseudo-selector to the value of the pseudoElement property.

    When assigning this property, the error-handling defined for the pseudoElement setter on the interface is applied. If the setter requires an exception to be thrown, this procedure must throw the same exception and abort all further steps.

    Otherwise,

    Set the target pseudo-selector to null.

  4. Let timing input be the result corresponding to the first matching condition from below.

    If options is a KeyframeEffectOptions object,

    Let timing input be options.

    Otherwise (if options is a double),

    Let timing input be a new EffectTiming object with all members set to their default values and duration set to options.

  5. Call the procedure to update the timing properties of an animation effect of effect from timing input.

    If that procedure causes an exception to be thrown, propagate the exception and abort this procedure.

  6. If options is a KeyframeEffectOptions object, assign the composite property of effect to the corresponding value from options.

    When assigning this property, the error-handling defined for the corresponding setter on the KeyframeEffect interface is applied. If the setter requires an exception to be thrown for the value specified by options, this procedure must throw the same exception and abort all further steps.

  7. Initialize the set of keyframes by performing the procedure defined for setKeyframes() passing keyframes as the input.

Element? target

The target element. This may be null for animations that do not target a specific element.

object? keyframes

The set of keyframes to use. The format and processing of this argument is defined in § 6.6.3 Processing a keyframes argument.

optional KeyframeEffectOptions options

Either a number specifying the iteration duration of the effect, or a collection of properties specifying the timing and behavior of the effect.

Examples of the usage of this constructor are given in § 6.6.1 Creating a new KeyframeEffect object.

KeyframeEffect (source)

Creates a new KeyframeEffect object with the same properties as source using the following procedure:

  1. Create a new KeyframeEffect object, effect.

  2. Set the following properties of effect using the corresponding values of source:

    Note: Unlike the KeyframeEffect(target, keyframes, options) constructor, we do not need to re-throw exceptions since the timing properties specified on source can be assumed to be valid.

KeyframeEffect source

The keyframe effect from which to copy the properties that define the new keyframe effect.

target, of type Element, nullable

The target element being animated by this object (either the effect target if it is an Element or its originating element if it is a pseudo-element). This may be null for animations that do not target a specific element such as an animation that produces a sound using an audio API.

pseudoElement, of type CSSOMString, nullable

The target pseudo-selector. null if this effect has no effect target or if the effect target is an element (i.e. not a pseudo-element). When the effect target is a pseudo-element, this specifies the pseudo-element selector (e.g. ::before).

On setting, sets the target pseudo-selector of the animation effect to the provided value after applying the following exceptions:

  • If the provided value is not null and is an invalid <pseudo-element-selector>, the user agent must throw a DOMException with error name SyntaxError and leave the target pseudo-selector of this animation effect unchanged.

    Note, that invalid in this context follows the definition of an invalid selector defined in [SELECTORS-4] such that syntactically invalid pseudo-elements as well as pseudo-elements for which the user agent has no usable level of support are both deemed invalid.

  • If one of the legacy Selectors Level 2 single-colon selectors (':before', ':after', ':first-letter', or ':first-line') is specified, the target pseudo-selector must be set to the equivalent two-colon selector (e.g. '::before').

composite, of type CompositeOperation

The composite operation used to composite this keyframe effect with the effect stack, as specified by one of the CompositeOperation enumeration values.

On setting, sets the composite operation property of this animation effect to the provided value.

sequence<object> getKeyframes()

Returns the keyframes that make up this effect along with their computed keyframe offsets.

This section is non-normative

The result of this method is a sequence of objects of the following format:

dictionary ComputedKeyframe {
    // ... property-value pairs ...
    // i.e. DOMString propertyName
    double?                  offset = null;
    double                   computedOffset;
    DOMString                easing = "linear";
    CompositeOperationOrAuto composite = "auto";
};

The meaning and values of each member is as follows:

offset

The keyframe offset of the keyframe specified as a number between 0.0 and 1.0 inclusive, or null.

This will be null if the keyframe is to be automatically spaced between adjacent keyframes.

computedOffset

The computed keyframe offset for this keyframe calculated as part of running the compute missing keyframe offsets procedure.

Unlike the offset member, the computedOffset is never null.

easing

The timing function used to transform the progress of time from this keyframe until the next keyframe in the series.

composite

The keyframe-specific composite operation used to combine the values specified in this keyframe with the underlying value.

This member will be auto if the composite operation specified on the keyframe effect is being used.

Since keyframes are represented by a partially open-ended dictionary type that is not currently able to be expressed with WebIDL, the procedure used to prepare the result of this method is defined in prose below:

  1. Let result be an empty sequence of objects.

  2. Let keyframes be one of the following:

    1. If this keyframe effect is associated with a CSSAnimation, and its keyframes have not been replaced by a successful call to setKeyframes(); the computed keyframes for this keyframe effect.

    2. Otherwise, the result of applying the procedure compute missing keyframe offsets to the keyframes for this keyframe effect.

    Note: We return computed keyframes for CSS Animations because not all keyframes specified in CSS can be represented by a dictionary.

  3. For each keyframe in keyframes perform the following steps:

    1. Initialize a dictionary object, output keyframe, using the following definition:

      dictionary BaseComputedKeyframe {
           double?                  offset = null;
           double                   computedOffset;
           DOMString                easing = "linear";
           CompositeOperationOrAuto composite = "auto";
      };
      
    2. Set the offset, computedOffset, easing, and composite members of output keyframe to the respective keyframe offset, computed keyframe offset, keyframe-specific timing function, and keyframe-specific composite operation values of keyframe.

    3. For each animation property-value pair in keyframe, declaration, perform the following steps:

      1. Let property name be the result of applying the animation property name to IDL attribute name algorithm to the property name of declaration.

      2. Let IDL value be the result of serializing the property value of declaration by passing declaration to the algorithm to serialize a CSS value [CSSOM].

      3. Let value be the result of converting IDL value to an ECMAScript String value.

      4. Call the [[DefineOwnProperty]] internal method on output keyframe with property name property name, Property Descriptor { [[Writable]]: true, [[Enumerable]]: true, [[Configurable]]: true, [[Value]]: value } and Boolean flag false.

    4. Append output keyframe to result.

  4. Return result.

void setKeyframes(object? keyframes)

Replaces the set of keyframes that make up this effect.

object? keyframes

A series of keyframes whose format and processing is defined by § 6.6.3 Processing a keyframes argument.

This effect’s set of keyframes is replaced with the result of performing the procedure to process a keyframes argument. If that procedure throws an exception, this effect’s keyframes are not modified.

6.6.1. Creating a new KeyframeEffect object

This section is non-normative

The KeyframeEffect constructor offers a number of approaches to creating new KeyframeEffect objects.

At its simplest, a KeyframeEffect object that changes the "left" property of elem to 100px over three seconds can be constructed as follows:

var effect = new KeyframeEffect(elem, { left: '100px' }, 3000);

The second parameter, representing the list of keyframes, may specify multiple properties. (See § 6.6.3 Processing a keyframes argument.)

// Specify multiple properties at once
var effectA = new KeyframeEffect(elem, { left: '100px', top: '300px' }, 3000);

// Specify multiple keyframes
var effectB = new KeyframeEffect(elem, [ { left: '100px' }, { left: '300px' } ], 3000);

The third parameter, representing the animation’s timing, may simply be a number representing the iteration duration in milliseconds as above, or, to specify further timing properties such as the start delay, an EffectTiming object can be used, as follows:

var effect =
  new KeyframeEffect(elem, { left: '100px' }, { duration: 3000, delay: 2000 });

If the duration is not specified, a value of zero is used. It is possible to create an animation that simply sets a property without any interpolation as follows:

var effect =
  new KeyframeEffect(elem, { visibility: 'hidden' }, { fill: 'forwards' });

As described in § 4.6 Fill behavior however, using indefinitely filling animations in this way is discouraged.

Having created a KeyframeEffect, it can be played by adding it to an Animation and then playing that animation. For simple effects, however, the Element.animate shortcut is more convenient since it performs these steps automatically. For example,

elem.animate({ left: '100px' }, 3000);

6.6.2. Property names and IDL names

The animation property name to IDL attribute name algorithm for property is as follows:

  1. If property follows the <custom-property-name> production, return property.

  2. If property refers to the CSS float property, return the string "cssFloat".

  3. If property refers to the CSS offset property, return the string "cssOffset".

  4. Otherwise, return the result of applying the CSS property to IDL attribute algorithm [CSSOM] to property.

The IDL attribute name to animation property name algorithm for attribute is as follows:

  1. If attribute conforms to the <custom-property-name> production, return attribute.

  2. If attribute is the string "cssFloat", then return an animation property representing the CSS float property.

  3. If attribute is the string "cssOffset", then return an animation property representing the CSS offset property.

  4. Otherwise, return the result of applying the IDL attribute to CSS property algorithm [CSSOM] to attribute.

6.6.3. Processing a keyframes argument

This section is non-normative

The following methods all accept a set of keyframes as an argument:

This argument may be specified in the one of two forms as illustrated below.

// The following two expressions produce the same result:
elem.animate([ { color: 'blue' },
               { color: 'green' },
               { color: 'red' },
               { color: 'yellow' } ], 2000);
elem.animate({ color: [ 'blue', 'green', 'red', 'yellow' ] }, 2000);

// Likewise, for a multi-property animation, the following two
// expressions are equivalent:
elem.animate([ { color: 'blue', left: '0px' },
               { color: 'green', left: '-20px' },
               { color: 'red', left: '100px' },
               { color: 'yellow', left: '50px'} ], 2000);
elem.animate({ color: [ 'blue', 'green', 'red', 'yellow' ],
               left: [ '0px', '-20px', '100px', '50px' ] }, 2000);

// Incidentally, the following three expressions are all equivalent:
elem.animate([ { color: 'red' } ], 1000);
elem.animate({ color: [ 'red' ] }, 1000);
elem.animate({ color: 'red' }, 1000);

The first form (the array-form) consists of an array of keyframes where each keyframe may specify at most one value per animation property. The second form (the object-form) consists of an object where each animation property may specify a single animation value or an array of animation values.

The first array-form is the canonical form and is the form returned by the getKeyframes() method.

Keyframe offsets can be specified using either form as illustrated below:

// The keyframes without offsets will automatically have offsets computed
// as 0 for the first keyframe, 0.65 for the middle keyframe, and 1 for the
// final keyframe.
elem.animate([ { color: 'blue' },
               { color: 'green', offset: 0.5 },
               { color: 'red' },
               { color: 'yellow', offset: 0.8 },
               { color: 'pink' } ], 2000);

// The following produces the same result. Note that it is not necessary to
// specify the last value: it will automatically be treated as 'null' and then
// the automatic assignment will apply as with the previous case.
elem.animate({ color: [ 'blue', 'green', 'red', 'yellow', 'pink' ],
               offset: [ null, 0.5, null, 0.8 ] }, 2000);

Likewise timing functions and keyframe-specific composite operations may be specified in either form. The array-form allows specifying different values for each keyframe whilst for the object-form, the list of values will be repeated as needed until each keyframe has been assigned a value.

// Since timing functions apply _between_ keyframes, even if we specify a
// a timing function on the last keyframe it will be ignored.
elem.animate([ { color: 'blue', easing: 'ease-in' },
               { color: 'green', easing: 'ease-out' },
               { color: 'yellow' } ], 2000);

// The following produces the same result.
elem.animate({ color: [ 'blue', 'green', 'yellow' ],
               easing: [ 'ease-in', 'ease-out' ] }, 2000);

// The repeating behavior makes assigning the same value to all keyframes
// simple:
elem.animate({ color: [ 'blue', 'green', 'yellow' ],
               easing: 'ease-in-out' }, 2000);

Note that the easing property in either form sets the keyframe-specific timing function. This is independent from the timing function that applies to the entire iteration duration of the keyframe effect as specified using a KeyframeEffectOptions object (or KeyframeAnimationOptions object when using the animate() method of the Animatable interface mixin).

In the following example, the two statements produce different results.

// Here, 'ease-in-out' is applied between each color value.
elem.animate({ color: [ 'blue', 'green', 'yellow' ],
               easing: 'ease-in-out' }, 2000);

// However, in this case, 'ease-in-out' is applied across the whole span
// of the animation, that is from 'blue' to 'yellow'.
elem.animate({ color: [ 'blue', 'green', 'yellow' ] },
             { duration: 2000, easing: 'ease-in-out' });

The type of the keyframes argument cannot be expressed in WebIDL since it relies on a partially-open dictionary type.

Conceptually, the type of this argument is equivalent to the following WebIDL-like definition:

dictionary Keyframe {
    // ... property-value pairs ...
    // i.e. DOMString propertyName
    double?                   offset = null;
    DOMString                 easing = "linear";
    CompositeOperationOrAuto  composite = "auto";
};

dictionary PropertyIndexedKeyframes {
    // ... property-value and property-valuelist pairs ...
    // i.e. (DOMString or sequence&lt;DOMString&gt;) propertyName
    (double? or sequence<double?>)                         offset = [];
    (DOMString or sequence<DOMString>)                     easing = [];
    (CompositeOperationOrAuto or sequence<CompositeOperationOrAuto>) composite = [];
};

typedef (sequence<Keyframe> or PropertyIndexedKeyframes) KeyframeArgument;

The meaning and allowed values of each argument is as follows:

offset

The keyframe offset of the keyframe specified as a number between 0.0 and 1.0 inclusive or null.

A null value indicates that the keyframe should be automatically spaced between adjacent keyframes.

Specifying an offset outside the range [0.0, 1.0] will cause a TypeError to be thrown.

Keyframes that specify an offset must be provided in increasing order of offset. Adjacent and equal offsets, however, are permitted.

easing

The timing function used to transform the progress of time from this keyframe until the next keyframe in the series.

The syntax and error-handling associated with parsing this string is identical to that defined for the easing attribute of the EffectTiming interface.

composite

The keyframe-specific composite operation used to combine the values specified in this keyframe with the underlying value.

If auto, the composite operation specified on the keyframe effect will be used.

Since this type cannot be expressed in WebIDL, its processing is defined in prose following.

For each method that takes a keyframes argument, the procedure to process a keyframes argument is run on the input and the result of that procedure is retained.

First we define two supporting definitions.

The instruction, check the completion record of result, where result is a completion record from calling an ECMAScript operation, is equivalent to the following steps:

  1. If result is an abrupt completion, throw the exception contained in the [[value]] field of result and abort the procedure.

    What should we do if the [[type]] is break, continue, or return? Can it be?

  2. Replace result with the value contained in the [[value]] field of result.

The procedure to process a keyframe-like object, takes two arguments:

and returns a map from either property names to DOMString values if allow lists is false, or from property names to sequences of DOMString values otherwise, using the following procedure:

  1. Run the procedure to convert an ECMAScript value to a dictionary type [WEBIDL] with keyframe input as the ECMAScript value, and the dictionary type depending on the value of the allow lists flag as follows:

    If allow lists is true,

    Use the following dictionary type:

    dictionary BasePropertyIndexedKeyframe {
        (double? or sequence<double?>)                         offset = [];
        (DOMString or sequence<DOMString>)                     easing = [];
        (CompositeOperationOrAuto or sequence<CompositeOperationOrAuto>) composite = [];
    };
    
    Otherwise,

    Use the following dictionary type,

    dictionary BaseKeyframe {
        double?                  offset = null;
        DOMString                easing = "linear";
        CompositeOperationOrAuto composite = "auto";
    };
    

    Store the result of this procedure as keyframe output.

  2. Build up a list of animatable properties as follows:

    1. Let animatable properties be a list of property names (including shorthand properties that have longhand sub-properties that are animatable) that can be animated by the implementation.

    2. Convert each property name in animatable properties to the equivalent IDL attribute by applying the animation property name to IDL attribute name algorithm.

  3. Let input properties be the result of calling the EnumerableOwnNames operation with keyframe input as the object.

  4. Make up a new list animation properties that consists of all of the properties that are in both input properties and animatable properties, or which are in input properties and conform to the <custom-property-name> production.

  5. Sort animation properties in ascending order by the Unicode codepoints that define each property name.

  6. For each property name in animation properties,

    1. Let raw value be the result of calling the [[Get]] internal method on keyframe input, with property name as the property key and keyframe input as the receiver.

    2. Check the completion record of raw value.

    3. Convert raw value to a DOMString or sequence of DOMStrings property values as follows:

      If allow lists is true,

      Let property values be the result of converting raw value to IDL type (DOMString or sequence<DOMString>) using the procedures defined for converting an ECMAScript value to an IDL value [WEBIDL].

      If property values is a single DOMString, replace property values with a sequence of DOMStrings with the original value of property values as the only element.

      Otherwise,

      Let property values be the result of converting raw value to a DOMString using the procedure for converting an ECMAScript value to a DOMString [WEBIDL].

    4. Calculate the normalized property name as the result of applying the IDL attribute name to animation property name algorithm to property name.

    5. Add a property to keyframe output with normalized property name as the property name, and property values as the property value.

  7. Return keyframe output.

The procedure to process a keyframes argument takes a nullable ECMAScript object, object, as input and returns a sequence of keyframes using the following procedure:

  1. If object is null, return an empty sequence of keyframes.

  2. Let processed keyframes be an empty sequence of keyframes.

  3. Let method be the result of GetMethod(object, @@iterator).

  4. Check the completion record of method.

  5. Perform the steps corresponding to the first matching condition from below,

    If method is not undefined,
    1. Let iter be GetIterator(object, method).

    2. Check the completion record of iter.

    3. Repeat:

      1. Let next be IteratorStep(iter).

      2. Check the completion record of next.

      3. If next is false abort this loop.

      4. Let nextItem be IteratorValue(next).

      5. Check the completion record of nextItem.

      6. If Type(nextItem) is not Undefined, Null or Object, then throw a TypeError and abort these steps.

      7. Append to processed keyframes the result of running the procedure to process a keyframe-like object passing nextItem as the keyframe input and with the allow lists flag set to false.

    Otherwise,
    1. Let property-indexed keyframe be the result of running the procedure to process a keyframe-like object passing object as the keyframe input and with the allow lists flag set to true.

    2. For each member, m, in property-indexed keyframe, perform the following steps:

      1. Let property name be the key for m.

      2. If property name is "composite", or "easing", or "offset", skip the remaining steps in this loop and continue from the next member in property-indexed keyframe after m.

      3. Let property values be the value for m.

      4. Let property keyframes be an empty sequence of keyframes.

      5. For each value, v, in property values perform the following steps:

        1. Let k be a new keyframe with a null keyframe offset.

        2. Add the property-value pair, property namev, to k.

        3. Append k to property keyframes.

      6. Apply the procedure to compute missing keyframe offsets to property keyframes.

      7. Add keyframes in property keyframes to processed keyframes.

    3. Sort processed keyframes by the computed keyframe offset of each keyframe in increasing order.

    4. Merge adjacent keyframes in processed keyframes when they have equal computed keyframe offsets.

    5. Let offsets be a sequence of nullable double values assigned based on the type of the "offset" member of the property-indexed keyframe as follows:

      sequence<double?>,

      The value of "offset" as-is.

      double?,

      A sequence of length one with the value of "offset" as its single item, i.e. « offset »,

    6. Assign each value in offsets to the keyframe offset of the keyframe with corresponding position in processed keyframes until the end of either sequence is reached.

    7. Let easings be a sequence of DOMString values assigned based on the type of the "easing" member of the property-indexed keyframe as follows:

      sequence<DOMString>,

      The value of "easing" as-is.

      DOMString,

      A sequence of length one with the value of "easing" as its single item, i.e. « easing »,

    8. If easings is an empty sequence, let it be a sequence of length one containing the single value "linear", i.e. « "linear" ».

    9. If easings has fewer items than processed keyframes, repeat the elements in easings successively starting from the beginning of the list until easings has as many items as processed keyframes.

      For example, if processed keyframes has five items, and easings is the sequence « "ease-in", "ease-out" », easings would be repeated to become « "ease-in", "ease-out", "ease-in", "ease-out", "ease-in" ».
    10. If easings has more items than processed keyframes, store the excess items as unused easings.

    11. Assign each value in easings to a property named "easing" on the keyframe with the corresponding position in processed keyframes until the end of processed keyframes is reached.

    12. If the "composite" member of the property-indexed keyframe is not an empty sequence:

      1. Let composite modes be a sequence of CompositeOperationOrAuto values assigned from the "composite" member of property-indexed keyframe. If that member is a single CompositeOperationOrAuto value operation, let composite modes be a sequence of length one, with the value of the "composite" as its single item.

      2. As with easings, if composite modes has fewer items than processed keyframes, repeat the elements in composite modes successively starting from the beginning of the list until composite modes has as many items as processed keyframes.

      3. Assign each value in composite modes that is not auto to the keyframe-specific composite operation on the keyframe with the corresponding position in processed keyframes until the end of processed keyframes is reached.

  6. If processed keyframes is not loosely sorted by offset, throw a TypeError and abort these steps.

  7. If there exist any keyframe in processed keyframes whose keyframe offset is non-null and less than zero or greater than one, throw a TypeError and abort these steps.

  8. For each frame in processed keyframes, perform the following steps:

    1. For each property-value pair in frame, parse the property value using the syntax specified for that property.

      If the property value is invalid according to the syntax for the property, discard the property-value pair. User agents that provide support for diagnosing errors in content SHOULD produce an appropriate warning highlighting the invalid property value.

    2. Let the timing function of frame be the result of parsing the "easing" property on frame using the CSS syntax defined for the easing member of the EffectTiming dictionary.

      If parsing the "easing" property fails, throw a TypeError and abort this procedure.

      Note: Using the CSS parser in both of the above steps implies that CSS comments and escaping are allowed but are not retained when the value is successfully parsed.

      Note: In the case where the "easing" property fails to parse, it is important that the TypeError is thrown after all reading the properties from object since failing to do so would be observable and will not match the behavior if partially open-ended dictionaries are later supported in WebIDL.

  9. Parse each of the values in unused easings using the CSS syntax defined for easing member of the EffectTiming interface, and if any of the values fail to parse, throw a TypeError and abort this procedure.

    This final step is required in order to provide consistent behavior such that a TypeError is thrown in all of the following cases:

    elem.animate({ easing: 'invalid' });
    elem.animate({ easing: ['invalid'] });
    elem.animate([{ easing: 'invalid' }]);
    

6.6.4. The KeyframeEffectOptions dictionary

Additional parameters may be passed to the KeyframeEffect(target, keyframes, options) constructor by providing a KeyframeEffectOptions object.

dictionary KeyframeEffectOptions : EffectTiming {
    CompositeOperation composite = "replace";
    CSSOMString?       pseudoElement = null;
};
composite, of type CompositeOperation, defaulting to "replace"

The composite operation used to composite this animation with the effect stack, as specified by one of the CompositeOperation enumeration values. This is used for all keyframes that specify a auto keyframe-specific composite operation.

pseudoElement, of type CSSOMString, nullable, defaulting to null

The pseudo-element selector (which must be valid or null) used to specify the effect target given the target element.

6.7. The CompositeOperation and CompositeOperationOrAuto enumerations

The possible values of an keyframe effect’s composition behavior are represented by the CompositeOperation enumeration.

enum CompositeOperation { "replace", "add", "accumulate" };
replace

Corresponds to the replace composite operation value such that the animation effect overrides the underlying value it is combined with.

add

Corresponds to the add composite operation value such that the animation effect is added to the underlying value with which it is combined.

accumulate

Corresponds to the accumulate composite operation value such that the animation effect is accumulated on to the underlying value.

The possible values of a keyframe's composition behavior share the same values as the CompositeOperation enumeration along with the additional auto value.

enum CompositeOperationOrAuto { "replace", "add", "accumulate", "auto" };
auto

Indicates that the composite operation of the associated keyframe effect should be used.

6.8. The Animatable interface mixin

Objects that may be the target of an KeyframeEffect object implement the Animatable interface mixin.

interface mixin Animatable {
    Animation           animate(object? keyframes,
                                optional (unrestricted double or KeyframeAnimationOptions) options = {});
    sequence<Animation> getAnimations(optional GetAnimationsOptions options = {});
};

dictionary KeyframeAnimationOptions : KeyframeEffectOptions {
    DOMString id = "";
    AnimationTimeline? timeline;
};

dictionary GetAnimationsOptions {
    boolean subtree = false;
};
Animation animate(keyframes, options)

Performs the following steps:

  1. Let target be the object on which this method was called.

  2. Construct a new KeyframeEffect object, effect, in the relevant Realm of target by using the same procedure as the KeyframeEffect(target, keyframes, options) constructor, passing target as the target argument, and the keyframes and options arguments as supplied.

    If the above procedure causes an exception to be thrown, propagate the exception and abort this procedure.

  3. If options is a KeyframeAnimationOptions object, let timeline be the timeline member of options or, if timeline member of options is missing, be the default document timeline of the node document of the element on which this method was called.

  4. Construct a new Animation object, animation, in the relevant Realm of target by using the same procedure as the Animation() constructor, passing effect and timeline as arguments of the same name.

  5. If options is a KeyframeAnimationOptions object, assign the value of the id member of options to animation’s id attribute.

  6. Run the procedure to play an animation for animation with the auto-rewind flag set to true.

  7. Return animation.

This section is non-normative

The following code fragment:

var animation = elem.animate({ opacity: 0 }, 2000);

is roughly equivalent to:

var effect = new KeyframeEffect(elem, { opacity: 0 }, 2000);
var animation = new Animation(effect, elem.ownerDocument.timeline);
animation.play();
keyframes

The keyframes to use. This value is passed to the KeyframeEffect(target, keyframes, options) constructor as the keyframes parameter and has the same interpretation as defined for that constructor.

options

The timing and animation options for the created KeyframeEffect and Animation.

sequence<Animation> getAnimations(options)

Returns the set of relevant Animation objects that contain at least one animation effect whose effect target is this object, or, if an options parameter is passed with subtree set to true, an inclusive descendant of this object or a pseudo-element of such a descendant.

An animation is relevant if:

For the purposes of this method a pseudo-element is considered to be a child of its originating element.

The returned list is sorted using the composite order described for the associated animations of effects in § 5.4.2 The effect stack.

Calling this method triggers a style change event for the target element. As a result, the returned list reflects the state after applying any pending style changes to animation such as changes to animation-related style properties that have yet to be processed.

options

Parameters governing the set of animations returned by getAnimations().

id, of type DOMString, defaulting to ""

The string to assign to the generated Animation's id attribute.

timeline, of type AnimationTimeline, nullable

An optional value which, if present, specifies the timeline with which to associate the newly-created animation.

subtree, of type boolean, defaulting to false

If true, indicates that animations associated with an animation effect whose target element is a descendant of the object on which getAnimations() is called should also be included in the result.

6.9. Extensions to the Document interface

The following extensions are made to the Document interface defined in [DOM].

partial interface Document {
    readonly attribute DocumentTimeline timeline;
};
timeline, of type DocumentTimeline, readonly

The DocumentTimeline object representing the default document timeline.

6.10. Extensions to the DocumentOrShadowRoot interface mixin

The following extensions are made to the DocumentOrShadowRoot interface mixin defined in [DOM].

partial interface mixin DocumentOrShadowRoot {
    sequence<Animation> getAnimations();
};
sequence<Animation> getAnimations()

Returns the set of relevant Animation objects that have an associated associated effect whose target element is a descendant of the document or shadow root on which this method is called.

The returned list is sorted using the composite order described for the associated animations of effects in § 5.4.2 The effect stack.

Calling this method triggers a style change event for the document. As a result, the returned list reflects the state after applying any pending style changes to animation such as changes to animation-related style properties that have yet to be processed.

6.11. Extensions to the Element interface

Since DOM Elements may be the target of an animation, the Element interface [DOM] is extended as follows:

Element includes Animatable;

This allows the following kind of usage.

elem.animate({ color: 'red' }, 2000);

6.12. The AnimationPlaybackEvent interface

Animation playback events are represented using the AnimationPlaybackEvent interface.

[Exposed=Window]
interface AnimationPlaybackEvent : Event {
    constructor(DOMString type, optional AnimationPlaybackEventInit eventInitDict = {});
    readonly attribute double? currentTime;
    readonly attribute double? timelineTime;
};
dictionary AnimationPlaybackEventInit : EventInit {
    double? currentTime = null;
    double? timelineTime = null;
};
AnimationPlaybackEvent(type, eventInitDict)

Constructs a new AnimationPlaybackEvent object using the procedure defined for constructing events [DOM].

currentTime, of type double, readonly, nullable

The current time of the animation that generated the event at the moment the event as queued. This will be null if the animation was idle at the time the event was generated.

timelineTime, of type double, readonly, nullable

The time value of the timeline with which the animation that generated the event is associated at the moment the event was queued. This will be null if the animation was not associated with an active timeline at the time the event was queued.

currentTime, of type double, nullable, defaulting to null

See the description of the currentTime attribute.

timelineTime, of type double, nullable, defaulting to null

See the description of the timelineTime attribute.

6.13. Model liveness

Changes made to any part of the model, cause the entire timing model to be updated and any dependent style.

Unless otherwise stated, invoking the methods or constructors, or getting or setting the members of interfaces defined in the programming interface section of this specification does not produce a style change event.

Note: Other specifications that extend this specification are expected to refine the requirements on style change events by introducing circumstances where such events are triggered. For example, when the interfaces in this specification represent animations defined by CSS markup, many of their methods will need to trigger style change events in order to reflect changes to the specified style.

This section is non-normative

Based on the above requirement and normative requirements elsewhere in this specification, the following invariants can be observed:

Changes made to the Web Animations model take effect immediately

For example, if the KeyframeEffect associated with an Animation is seeked (see § 4.4.4 Setting the current time of an animation) via the programming interface, the value returned when querying the animation’s startTime will reflect updated state of the model immediately.

// Initially animation.effect.getComputedTiming().localTime is 3000
animation.currentTime += 2000;
alert(animation.effect.getComputedTiming().localTime); // Displays "5000"
Querying the computed style of a property affected by animation returns the fully up-to-date state of the animation

For example, if the used style of an element is queried immediately after applying a new Animation to that element, the result of the new animation will be incorporated in the value returned.

// Set opacity to 0 immediately
elem.animate({ opacity: 0 }, { fill: 'forwards' });
alert(window.getComputedStyle(elem).opacity); // Displays "0"
Changes made within the same task are synchronized such that the whole set of changes is rendered together

As a result of changes to the model taking effect immediately combined with ECMAScript’s run-to-completion semantics, there should never be a situation where, for example, only the changes to specified style are rendered without applying animation.

// Fade the opacity with fallback for browsers that don’t
// support Element.animate
elem.style.opacity = '0';
elem.animate([ { opacity: 1 }, { opacity: 0 } ], 500);

Note, however, that in the example above, a user agent may render a frame with none of the above changes applied. This might happen, for example, if rendering occurs in a separate process that is scheduled to run shortly after the above task completes but before the changes can be communicated to the process.

The value returned by the currentTime attribute of a document timeline will not change within a task

Due to the requirement on timelines to update their current time each time the update animations and send events procedure is run, querying the currentTime twice within a long block of code that is executed in the same script block will return the same value as shown in the following example.

var a = document.timeline.currentTime;
// ... many lines of code ...
var b = document.timeline.currentTime;
alert(b - a); // Displays 0
The time passed to a requestAnimationFrame callback will be equal to document.timeline.currentTime

Since HTML’s event loop processing model defines that the procedure to update animations and send events is performed prior to running animation frame callbacks, and since the time passed to such callbacks is the same now timestamp is passed to both procedures, the current time of a the default document timeline should match the time passed to requestAnimationFrame.

window.requestAnimationFrame(function(now) {
  // Displays 0
  alert(now - document.timeline.currentTime);
});
Calling methods from this programming interface will generally not cause transitions to be triggered

Consider the following example:

// Setup transition start point
div.style.opacity = '1';
getComputedStyle(div).opacity;

// Setup transition end point
div.style.transition = 'opacity 1s';
div.style.opacity = '0';

// Fire an animation
div.animate({ opacity: [0.5, 1] }, 500);

// Wait for the transition to end -- the following will never be called!
div.addEventListener('transitionend', () => {
  console.log('transitionend');
});

In this case, calling animate() will not trigger a style change event. As a result, the pending style change will be processed at the same time as the style change resulting from the new animation. Since the animation style will override the before-change style and the after-change style, no transition will be generated and the event handler for the transitionend event will never be called.

7. Integration with Media Fragments

The Media Fragments specification [MEDIA-FRAGS] defines a means for addressing a temporal range of a media resource. The application of media fragments depends on the MIME type of the resource on which they are specified. For resources with the SVG MIME type [SVG11], the application of temporal parameters is defined in the Animation Elements specification.

Note: media fragments are defined to operate on resources based on their MIME type. As a result, temporal addressing may not be supported in all situations where Web Animations content is used.

8. Interaction with page display

HTML permits user agents to store user-agent defined state along with a session history entry so that as a user navigates between pages, the previous state of the page can be restored including state such as scroll position [HTML].

User agents that pause and resume media elements when the referencing document is unloaded and traversed, are encouraged to apply consistent handling to documents containing Web Animations content. If provided, this behavior SHOULD be achieved by adjusting the time values of any timelines that track wallclock time.

Is this at odds with those time values being relative to navigationStart and with requestAnimationFrame using the same time as document.timeline.currentTime? [Issue #2083]

9. Implementation requirements

9.1. Precision of time values

The internal representation of time values is implementation dependent however, it is RECOMMENDED that user agents be able to represent input time values with microsecond precision so that a time value (which nominally represents milliseconds) of 0.001 is distinguishable from 0.0.

9.2. Conformance criteria

This specification defines an abstract model for animation and, as such, for user agents that do not support scripting, there are no conformance criteria since there is no testable surface area.

User agents that do not support scripting, however, may implement additional technologies defined in terms of this specification in which case the definitions provided in this specification will form part of the conformance criteria of the additional technology.

A conforming scripted Web Animations user agent is a user agent that implements the API defined in § 6 Programming interface.

10. Acknowledgements

Thank you to Steve Block, Michael Giuffrida, Ryan Seys, and Eric Willigers for their contributions to this specification.

Thank you also to Michiel "Pomax" Kamermans for help with the equations for a proposed smooth timing function although this feature has been deferred to a subsequent specification.

Our deep gratitude goes out to Southern Star Animation for their kind generosity and patience in introducing the editors to the processes and techniques used producing broadcast animations.

11. Changes since last publication

The following changes have been made since the 8 September 2022 Working Draft:

The changelog provides a more detailed history.

Appendix A: Animation types of existing properties

Typically the animation type of a property is included along with its definition. However, for some properties defined in older or very mature specifications the animation type information is not included. All such properties are assumed to have an animation type of by computed value unless they are one of the exceptions listed below.

Animation of font-weight

font-weight property values prior to level 4 are combined as follows:

Note: This definition is obsoleted by [CSS-FONTS-4] where the requirement that a font-weight value be a multiple of 100 is dropped. At that point the animation type for font-weight is simply by computed value.

Animation of visibility

For the visibility property, visible is interpolated as a discrete step where values of p between 0 and 1 map to visible and other values of p map to the closer endpoint; if neither value is visible then discrete animation is used.

Animation of box-shadow and text-shadow

Animation the box-shadow or text-shadow property follows the procedures for combining shadow lists as follows:

Each shadow in the list (treating none as a 0-length list) is interpolated component-wise as with by computed value behavior. However, if both input shadows are inset or both input shadows are not inset, then the interpolated shadow must match the input shadows in that regard. If any pair of input shadows has one inset and the other not inset, the entire shadow-list uses discrete animation. If the lists of shadows have different lengths, then the shorter list is padded at the end with shadows whose color is transparent, all lengths are 0, and whose inset (or not) matches the longer list.

Addition of two shadow lists Va and Vb is defined as list concatenation such that Vresult is equal to Va extended with Vb.

Accumulation of shadow lists follows the matching rules for interpolation above, performing addition on each component according to its type, or falling back to discrete animation if the inset values do not match.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Tests

Tests relating to the content of this specification may be documented in “Tests” blocks like this one. Any such block is non-normative.


Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Partial implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Non-experimental implementations

Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-ANIMATIONS-1]
Dean Jackson; et al. CSS Animations Level 1. URL: https://andreubotella.com/csswg-auto-build/test/css-animations/
[CSS-ANIMATIONS-2]
CSS Animations Module Level 2 URL: https://drafts.csswg.org/css-animations-2/
[CSS-BACKGROUNDS-3]
Bert Bos; Elika Etemad; Brad Kemper. CSS Backgrounds and Borders Module Level 3. URL: https://andreubotella.com/csswg-auto-build/test/css-backgrounds/
[CSS-CASCADE-3]
Elika Etemad; Tab Atkins Jr.. CSS Cascading and Inheritance Level 3. URL: https://andreubotella.com/csswg-auto-build/test/css-cascade-3/
[CSS-CASCADE-5]
Elika Etemad; Miriam Suzanne; Tab Atkins Jr.. CSS Cascading and Inheritance Level 5. URL: https://andreubotella.com/csswg-auto-build/test/css-cascade-5/
[CSS-COLOR-4]
Tab Atkins Jr.; Chris Lilley; Lea Verou. CSS Color Module Level 4. URL: https://andreubotella.com/csswg-auto-build/test/css-color/
[CSS-DISPLAY-3]
Tab Atkins Jr.; Elika Etemad. CSS Display Module Level 3. URL: https://andreubotella.com/csswg-auto-build/test/css-display/
[CSS-EASING-1]
Brian Birtles; et al. CSS Easing Functions Level 1. URL: https://andreubotella.com/csswg-auto-build/test/css-easing/
[CSS-EASING-2]
CSS Easing Functions Level 2 URL: https://drafts.csswg.org/css-easing/
[CSS-FONTS-4]
John Daggett; Myles Maxfield; Chris Lilley. CSS Fonts Module Level 4. URL: https://andreubotella.com/csswg-auto-build/test/css-fonts-4/
[CSS-LOGICAL-1]
Rossen Atanassov; Elika Etemad. CSS Logical Properties and Values Level 1. URL: https://andreubotella.com/csswg-auto-build/test/css-logical-1/
[CSS-PROPERTIES-VALUES-API-1]
Tab Atkins Jr.; et al. CSS Properties and Values API Level 1. URL: https://drafts.css-houdini.org/css-properties-values-api-1/
[CSS-SHADOW-PARTS-1]
Tab Atkins Jr.; Fergal Daly. CSS Shadow Parts. URL: https://andreubotella.com/csswg-auto-build/test/css-shadow-parts/
[CSS-STYLE-ATTR]
Tantek Çelik; Elika Etemad. CSS Style Attributes. URL: https://andreubotella.com/csswg-auto-build/test/css-style-attr/
[CSS-TEXT-DECOR-4]
Elika Etemad; Koji Ishii. CSS Text Decoration Module Level 4. URL: https://andreubotella.com/csswg-auto-build/test/css-text-decor-4/
[CSS-TRANSFORMS-1]
Simon Fraser; et al. CSS Transforms Module Level 1. URL: https://andreubotella.com/csswg-auto-build/test/css-transforms/
[CSS-TRANSITIONS-1]
David Baron; et al. CSS Transitions. URL: https://andreubotella.com/csswg-auto-build/test/css-transitions/
[CSS-TRANSITIONS-2]
CSS Transitions Module Level 2 URL: https://drafts.csswg.org/css-transitions-2/
[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. URL: https://andreubotella.com/csswg-auto-build/test/css-values-4/
[CSS-VARIABLES-2]
CSS Variables Module Level 2 URL: https://drafts.csswg.org/css-variables-2/
[CSS-WILL-CHANGE-1]
Tab Atkins Jr.. CSS Will Change Module Level 1. URL: https://andreubotella.com/csswg-auto-build/test/css-will-change/
[CSS-WRITING-MODES-3]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 3. URL: https://andreubotella.com/csswg-auto-build/test/css-writing-modes-3/
[CSS-WRITING-MODES-4]
Elika Etemad; Koji Ishii. CSS Writing Modes Level 4. URL: https://andreubotella.com/csswg-auto-build/test/css-writing-modes-4/
[CSS21]
Bert Bos; et al. Cascading Style Sheets Level 2 Revision 1 (CSS 2.1) Specification. URL: https://andreubotella.com/csswg-auto-build/test/css2/
[CSSOM]
Daniel Glazman; Emilio Cobos Álvarez. CSS Object Model (CSSOM). URL: https://andreubotella.com/csswg-auto-build/test/cssom/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[ECMASCRIPT]
ECMAScript Language Specification. URL: https://tc39.es/ecma262/multipage/
[HR-TIME]
Yoav Weiss. High Resolution Time. URL: https://w3c.github.io/hr-time/
[HTML]
Anne van Kesteren; et al. HTML Standard. Living Standard. URL: https://html.spec.whatwg.org/multipage/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[MEDIA-FRAGS]
Raphaël Troncy; et al. Media Fragments URI 1.0 (basic). 25 September 2012. REC. URL: https://www.w3.org/TR/media-frags/
[MOTION-1]
Dirk Schulze; et al. Motion Path Module Level 1. URL: https://drafts.fxtf.org/motion-1/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SELECT]
Tantek Çelik; et al. Selectors Level 3. URL: https://andreubotella.com/csswg-auto-build/test/selectors-3/
[SELECTORS-4]
Elika Etemad; Tab Atkins Jr.. Selectors Level 4. URL: https://andreubotella.com/csswg-auto-build/test/selectors/
[SVG11]
Erik Dahlström; et al. Scalable Vector Graphics (SVG) 1.1 (Second Edition). 16 August 2011. REC. URL: https://www.w3.org/TR/SVG11/
[SVG2]
Amelia Bellamy-Royds; et al. Scalable Vector Graphics (SVG) 2. URL: https://svgwg.org/svg2-draft/
[WEB-ANIMATIONS-2]
Web Animations Module Level 2 URL: https://drafts.csswg.org/web-animations-2/
[WEBIDL]
Edgar Chen; Timothy Gu. Web IDL Standard. Living Standard. URL: https://webidl.spec.whatwg.org/

Informative References

[SMIL-ANIMATION]
Patrick Schmitz; Aaron Cohen. SMIL Animation. 4 September 2001. REC. URL: https://www.w3.org/TR/smil-animation/

IDL Index

[Exposed=Window]
interface AnimationTimeline {
    readonly attribute double? currentTime;
};

dictionary DocumentTimelineOptions {
  DOMHighResTimeStamp originTime = 0;
};

[Exposed=Window]
interface DocumentTimeline : AnimationTimeline {
  constructor(optional DocumentTimelineOptions options = {});
};

[Exposed=Window]
interface Animation : EventTarget {
    constructor(optional AnimationEffect? effect = null,
                optional AnimationTimeline? timeline);
             attribute DOMString                id;
             attribute AnimationEffect?         effect;
             attribute AnimationTimeline?       timeline;
             attribute double?                  startTime;
             attribute double?                  currentTime;
             attribute double                   playbackRate;
    readonly attribute AnimationPlayState       playState;
    readonly attribute AnimationReplaceState    replaceState;
    readonly attribute boolean                  pending;
    readonly attribute Promise<Animation>       ready;
    readonly attribute Promise<Animation>       finished;
             attribute EventHandler             onfinish;
             attribute EventHandler             oncancel;
             attribute EventHandler             onremove;
    undefined cancel();
    undefined finish();
    undefined play();
    undefined pause();
    undefined updatePlaybackRate(double playbackRate);
    undefined reverse();
    undefined persist();
    [CEReactions]
    undefined commitStyles();
};

enum AnimationPlayState { "idle", "running", "paused", "finished" };

enum AnimationReplaceState { "active", "removed", "persisted" };

[Exposed=Window]
interface AnimationEffect {
    EffectTiming         getTiming();
    ComputedEffectTiming getComputedTiming();
    undefined            updateTiming(optional OptionalEffectTiming timing = {});
};

dictionary EffectTiming {
    double                             delay = 0;
    double                             endDelay = 0;
    FillMode                           fill = "auto";
    double                             iterationStart = 0.0;
    unrestricted double                iterations = 1.0;
    (unrestricted double or DOMString) duration = "auto";
    PlaybackDirection                  direction = "normal";
    DOMString                          easing = "linear";
};

dictionary OptionalEffectTiming {
    double                             delay;
    double                             endDelay;
    FillMode                           fill;
    double                             iterationStart;
    unrestricted double                iterations;
    (unrestricted double or DOMString) duration;
    PlaybackDirection                  direction;
    DOMString                          easing;
};

enum FillMode { "none", "forwards", "backwards", "both", "auto" };

enum PlaybackDirection { "normal", "reverse", "alternate", "alternate-reverse" };

dictionary ComputedEffectTiming : EffectTiming {
    unrestricted double  endTime;
    unrestricted double  activeDuration;
    double?              localTime;
    double?              progress;
    unrestricted double? currentIteration;
};

[Exposed=Window]
interface KeyframeEffect : AnimationEffect {
    constructor(Element? target,
                object? keyframes,
                optional (unrestricted double or KeyframeEffectOptions) options = {});
    constructor(KeyframeEffect source);
    attribute Element?           target;
    attribute CSSOMString?       pseudoElement;
    attribute CompositeOperation composite;
    sequence<object> getKeyframes();
    undefined        setKeyframes(object? keyframes);
};

dictionary BaseComputedKeyframe {
     double?                  offset = null;
     double                   computedOffset;
     DOMString                easing = "linear";
     CompositeOperationOrAuto composite = "auto";
};

dictionary BasePropertyIndexedKeyframe {
    (double? or sequence<double?>)                         offset = [];
    (DOMString or sequence<DOMString>)                     easing = [];
    (CompositeOperationOrAuto or sequence<CompositeOperationOrAuto>) composite = [];
};

dictionary BaseKeyframe {
    double?                  offset = null;
    DOMString                easing = "linear";
    CompositeOperationOrAuto composite = "auto";
};

dictionary KeyframeEffectOptions : EffectTiming {
    CompositeOperation composite = "replace";
    CSSOMString?       pseudoElement = null;
};

enum CompositeOperation { "replace", "add", "accumulate" };

enum CompositeOperationOrAuto { "replace", "add", "accumulate", "auto" };

interface mixin Animatable {
    Animation           animate(object? keyframes,
                                optional (unrestricted double or KeyframeAnimationOptions) options = {});
    sequence<Animation> getAnimations(optional GetAnimationsOptions options = {});
};

dictionary KeyframeAnimationOptions : KeyframeEffectOptions {
    DOMString id = "";
    AnimationTimeline? timeline;
};

dictionary GetAnimationsOptions {
    boolean subtree = false;
};

partial interface Document {
    readonly attribute DocumentTimeline timeline;
};

partial interface mixin DocumentOrShadowRoot {
    sequence<Animation> getAnimations();
};

Element includes Animatable;

[Exposed=Window]
interface AnimationPlaybackEvent : Event {
    constructor(DOMString type, optional AnimationPlaybackEventInit eventInitDict = {});
    readonly attribute double? currentTime;
    readonly attribute double? timelineTime;
};
dictionary AnimationPlaybackEventInit : EventInit {
    double? currentTime = null;
    double? timelineTime = null;
};

Issues Index

There must be a better term than "origin time"— it’s too similar to "time origin". [Issue #2079]
In the presence of certain timing functions, the input iteration progress to an animation effect is not limited to the range [0, 1]. Currently, however, keyframe offsets are limited to the range [0, 1] and property values are simply extrapolated for input iteration progress values outside this range.

We have considered removing this restriction since some cases exist where it is useful to be able to specify non-linear changes in property values at iteration progress values outside the range [0, 1]. One example is an animation that interpolates from green to yellow but has an overshoot timing function that makes it temporarily interpolate "beyond" yellow to red before settling back to yellow.

While this effect could be achieved by modification of the keyframes and timing function, this approach seems to break the model’s separation of timing concerns from animation effects.

It is not clear how this effect should be achieved but we note that allowing keyframe offsets outside [0, 1] may make the currently specified behavior where keyframes at offset 0 and 1 are synthesized as necessary, inconsistent.

See section 4 (Keyframe offsets outside [0, 1]) of minuted discussion from Tokyo 2013 F2F.

<https://github.com/w3c/csswg-drafts/issues/2081>

The definition of being rendered [HTML] with regards to display: contents is still under discussion. For the purpose of this procedure, we assume that an element with display: contents that otherwise would have associated layout boxes (i.e. it is connected and not part of a display: none subtree) is being rendered.

The remove() method can be used to remove an effect from either its parent group or animation. Should we keep it in level 1 and define it simply as removing the animation effect from its animation? [Issue #2082]
What should we do if the [[type]] is break, continue, or return? Can it be?
Is this at odds with those time values being relative to navigationStart and with requestAnimationFrame using the same time as document.timeline.currentTime? [Issue #2083]