Web Animations

1. Introduction

// 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');
});

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:

For example, consider an animation that:

• starts after 3 seconds

• runs twice,

• takes 2 seconds every time, and

• changes the width of a rectangle from 50 pixels to 100 pixels.

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.

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:

   • Updating the current time of any animations associated with the timeline.

   • Running the update an animation’s finished state procedure for any animations whose current time has been updated.

   • Queueing animation events for any such animations.

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.

4.4. Animations

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:

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:

   • animation’s hold time is resolved, or

   • animation’s start time is unresolved, or

   • animation has no associated timeline or the associated timeline is inactive, or

   • animation’s playback rate is 0,

   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

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

• the user agent has completed any setup required to begin the playback of the animation’s associated effect including rendering the first frame of any keyframe effect.

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

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).

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:

   • unresolved, or

   • less than zero, or

   • greater than or equal to associated effect end,

   Set seek time to zero.

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

   • unresolved, or

   • less than or equal to zero, or

   • greater than associated effect end,

   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:

   • seek time is unresolved, and

   • animation’s start time is unresolved, and

   • animation’s current time is unresolved,

   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:

    • animation’s hold time is unresolved, and

    • seek time is unresolved, and

    • aborted pause is false, and

    • animation does not have a pending playback rate,

    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.

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,

   • the unconstrained current time is resolved, and

   • animation’s start time is resolved, and

   • animation does not have a pending play task or a pending pause task,

   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.

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

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;

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

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:

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

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.

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:

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.

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:

• the animation effect is in play, or

• the animation effect is associated with an animation with a playback rate > 0 and the animation effect is in the before phase, or

• the animation effect is associated with an animation with a playback rate < 0 and the animation effect is in the after phase.

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:

• none,

• forwards,

• backwards, and

• both.

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

// 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)';
});

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

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.

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.

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.

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.

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.

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.

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.

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.

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,

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,

   • the simple iteration progress calculated above is zero, and

   • the animation effect is in the active phase or the after phase, and

   • the active time is equal to the active duration, and

   • the iteration count is not equal to zero.

   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:

• normal,

• reverse,

• alternate, or

• alternate-reverse.

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

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

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 V_a to V_b at 50% (p=0.5), i.e.

$V_{\mathrm{result}}=\left\{\begin{array}{cc}{V}_{\mathrm{start}}\hfill & \text{if }p<0.5\hfill \\ V_{\mathrm{end}}\hfill & \text{if }p\ge 0.5\hfill \end{array}\right.$

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

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

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:

   • A appears before B in keyframes, and

   • A and B have a computed keyframe offset that is not null, and

   • all keyframes between A and B have a null computed keyframe offset,

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

   1. Let offset_k 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 offset_A + (offset_B − offset_A) × 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:

      • Compute a property value using the value specified on keyframe as the value, and the target element as the element; then add the property and resulting value to computed keyframe.

      • For shorthand properties, add the equivalent longhand properties.

      • For logical properties [CSS-LOGICAL-1], add the equivalent physical properties [CSS-WRITING-MODES-4] based on the computed value of writing-mode and/or direction for the effect target.

      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 (V_a) and value to combine (V_b) 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 V_start and the second as V_end and using transformed distance as the interpolation parameter p.

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.

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:

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.

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]).

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

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

5.5.1. Replace state

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

• active

• removed

• persisted

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:

• The existence of the animation is not prescribed by markup. That is, it is not a CSS animation with an owning element, nor a CSS transition with an owning element.

• The animation's play state is finished.

• The animation's replace state is not removed.

• The animation is associated with a monotonically increasing timeline.

• The animation has an associated effect.

• The animation's associated effect is in effect.

• The animation's associated effect has an effect target.

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

• has an associated animation effect whose effect target is a descendant of doc, and

• is replaceable, and

• has a replace state of active, and

• for which there exists for each target property of every animation effect associated with animation, an animation effect associated with a replaceable animation with a higher composite order than animation that includes the same target property

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.

6. Programming interface

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;
};

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 = {});
};

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();
};

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 = {});
};

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;
};

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:

   • delay → start delay

   • endDelay → end delay

   • fill → fill mode

   • iterationStart → iteration start

   • iterations → iteration count

   • duration → iteration duration

   • direction → playback direction

   • easing → timing function

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;
};

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);
};

6.6.1. Creating a new KeyframeEffect object

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

// 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);

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

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

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

// 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 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);

// 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);

// 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' });

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<DOMString>) propertyName
    (double? or sequence<double?>)                         offset = [];
    (DOMString or sequence<DOMString>)                     easing = [];
    (CompositeOperationOrAuto or sequence<CompositeOperationOrAuto>) composite = [];
};

typedef (sequence<Keyframe> or PropertyIndexedKeyframes) KeyframeArgument;

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:

• an ECMAScript object, keyframe input, and

• an allow lists boolean flag

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 name → v, 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;
};