Web Animations

1. Introduction

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

3. Timing model

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

3.1. The timing model at a glance

3.2. Timing model concepts

In Web Animations, 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 we may have timelines that are based on 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.

Periodically, the user agent will update the timing model in a process called sampling. On each sample the time values of each timing node are updated.

Further requirements on the frequency and sequencing of sampling are specified by HTML’s event loop processing model [HTML].

Note: HTML currently refers to a “run CSS animations and send events” operation but this should be understood to include sampling all animations covered by this specification, not only CSS animations. Furthermore, the now parameter passed to this operation is ignored in this specification since we define a more general model that supports timelines whose time origin is not relative to navigationStart.

3.3. The global clock

At the root of the Web Animations timing hierarchy is the global clock.

The global clock is a source of monotonically increasing time values unaffected by adjustments to the system clock. The time values produced by the global clock represent wall-clock milliseconds from an unspecified historical moment. Because the zero time of the global clock is not specified, the absolute values of the time values produced by the global clock are not significant, only their rate of change.

Note: The global clock is not exposed in the programming interface and nor is it expected to be exposed by markup. As a result, the moment from which global clock time values are measured, that is, the zero time of the clock, is implementation-dependent. One user agent may measure the number of milliseconds since the user agent was loaded whilst another may use the time when the device was started. Both approaches are acceptable and produce no observable difference in the output of the model.

3.4. Timelines

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

Typically, a timeline is tied to the global clock such that its absolute time is calculated as a fixed offset from the time of the global clock. This offset is established by designating some moment as the timeline’s zero time and recording the time value of the global clock at that moment. At subsequent moments, the time value of the timeline is calculated as the difference between the current time value of the global clock and the value recorded as the zero time.

On each sample, the time value of the global clock at the beginning of the sample is recorded and this recorded value is used as the time value of the global clock until the next sample.

Note: We anticipate that other types of timelines may be introduced in the future that are not tied to the global clock. For example, a timeline whose time values are related to the progress of a scroll container or UI gesture.

Since a timeline may be defined relative to a moment that has yet to occur, it may not always be able to return a meaningful time value, but only an unresolved time value. A timeline is considered to be inactive when its time value is unresolved.

3.4.1. Document timelines

A document timeline is a type of timeline that is associated with a document.

The time values of a document timeline are calculated as a fixed offset from the global clock such that the zero time corresponds to the navigationStart moment [NAVIGATION-TIMING] plus a signed delta known as the origin time. Prior to establishing the navigationStart moment, the document timeline is inactive.

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

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

3.5. Animations

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

An animation’s start time is the time value of its timeline when its target 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 §4.5.1 Animation classes).

3.5.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 animation 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.

3.5.2. Responding to a newly inactive timeline

With the set of timelines defined in this level of this specification, this situation is not expected to occur. As a result, this section will likely be moved to a subsequent level of this specification.

When the timeline associated with an animation, animation, becomes newly inactive, if animation’s previous current time is resolved, the procedure to silently set the current time of animation to previous current time is run.

3.5.3. Setting the target effect of an animation

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

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

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

3. If new effect is null and old effect is not null, run the procedure to reset an animation’s pending tasks on animation.

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

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

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

7. Let the target effect of animation be new effect.

8. 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. Reject animation’s current ready promise with a DOMException named "AbortError".

   If cancelable promises materialize, we should probably cancel here instead of rejecting.

5. Let animation’s current ready promise be the result of creating a new resolved Promise object.

3.5.4. The current time of an animation

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

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

3.5.5. 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 split into 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 animation 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. Make animation’s start time unresolved.

   3. Cancel the pending pause task.

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

3.5.6. Setting the start time of an animation

The procedure to set the animation start time of animation, animation, to start time, 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 animation 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. Set animation’s start time to new start time.

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

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

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

3.5.7. Waiting for the target 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 target effect including rendering the first frame of any keyframe effect.

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

3.5.8. Promise objects

Promise objects are defined by [ECMA-262].

To resolve a Promise with value, call the [[Call]] internal [[Resolve]] method on the PromiseCapability record for the promise, passing undefined as thisArgument and (value) as argumentsList.

To reject a Promise with reason, call the [[Call]] internal [[Reject]] method on the PromiseCapability record for the promise, passing undefined as thisArgument and (reason) as argumentsList.

To create a new resolved Promise with value, call Promise.resolve, passing value as x.

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

The object is replaced with a new Promise object every time the animation enters the pending play state as well as when the animation is canceled (see §3.5.16 Canceling an animation).

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

3.5.10. Playing an animation

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

Note: The auto-rewind flag is provided for other specifications that build on this model but do not require the rewinding behavior, such as CSS Animations [CSS3-ANIMATIONS].

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. Perform the steps corresponding to the first matching condition from the following, if any:

   If animation playback rate > 0, the auto-rewind flag is true and either animation’s:

   • current time is unresolved, or

   • current time < zero, or

   • current time ≥ target effect end,

   Set animation’s hold time to zero.

   If animation playback rate < 0, the auto-rewind flag is true and either animation’s:

   • current time is unresolved, or

   • current time ≤ zero, or

   • current time > target effect end,

   If target effect end is positive infinity, throw an InvalidStateError and abort these steps. Otherwise, set animation’s hold time to target effect end.

   If animation playback rate = 0 and animation’s current time is unresolved,

   Set animation’s hold time to zero.

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

   1. Cancel that task.

   2. Set has pending ready promise to true.

5. If animation’s hold time is unresolved and aborted pause is false, abort this procedure.

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

7. If has pending ready promise is false, let animation’s current ready promise be a new (pending) Promise object.

8. Schedule a task to run as soon as animation is ready. 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 animation became ready.

   2. If animation’s start time is unresolved, perform the following steps:

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

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

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

   3. Resolve animation’s current ready promise with 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.

      Note that the order of the above two steps is important since it means that an animation with zero-length target 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.

      A user agent MAY execute the above task immediately (if it determines animation is immediately ready) thereby bypassing the pending play state altogether.

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

3.5.11. 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 §3.5.7 Waiting for the target 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. 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,

   Let animation’s hold time be zero.

   Otherwise,

   If target effect end for animation is positive infinity, throw an InvalidStateError and abort these steps. Otherwise, let animation’s hold time be target effect end.

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

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

6. If has pending ready promise is false, set animation’s current ready promise to a new (pending) Promise object.

7. Schedule a task to be executed at the first possible moment after the user agent has performed any processing necessary to suspend the playback of animation’s target effect, if any. 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 target 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 is pending, waiting to begin playback. In either case we want to preserve the hold time as we enter the paused state.

   3. Make animation’s start time unresolved.

   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.

   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.

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

3.5.12. 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 target 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 target 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 target effect to 5s. If target 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 target effect changes.

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

3.5.13. 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 (pending) Promise object every time the animation leaves the finished play state.

3.5.14. Updating the finished state

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

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

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 animation 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 on each sample and each time the timing properties of the target effect associated with an animation are updated. 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. If both of the following conditions are true,

   • 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 animation playback rate > 0 and current time is resolved and greater than or equal to target effect end,

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

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

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

   If did seek is true, let the hold time be the value of 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 current time is resolved, and animation 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.

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

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

4. 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. Queue a task to fire a finish event 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.

5. If current finished state is false and animation’s current finished promise is already resolved, set animation’s current finished promise to a new (pending) Promise object.

var animation = elem.animate({ left: '100px' }, 2000);
animation.playbackRate = 2;
animation.currentTime = 1000; // animation is now finished
animation.effect.timing.iterationCount = 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;

3.5.15. 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 playback rate is zero, or if animation playback rate > 0 and target effect end is infinity, throw an InvalidStateError and abort these steps.

2. Set limit as follows:

   If animation playback rate > 0,

   Let limit be target effect end.

   Otherwise,

   Let limit be zero.

3. Silently set the current time to limit.

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

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

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

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

3.5.16. Canceling an animation

An animation can be canceled which causes the current time to become unresolved hence removing any effects caused by the target 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".

      If cancelable promises materialize, we should cancel here instead of rejecting.

   3. Let current finished promise be a new (pending) Promise object.

   4. If animation is not idle, queue a task to fire a cancel event at animation. The task source for this task is the DOM manipulation task source.

      The event current time for the dispatched cancel event is unresolved and the event timeline time is the current time value of the timeline associated with animation at the moment the task is queued.

2. Make animation’s hold time unresolved.

3. Make animation’s start time unresolved.

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

3.5.17.1. Updating the playback rate of an animation

Changes to the playback rate trigger a compensatory seek so that that the animation’s current time is unaffected by the change to the playback rate.

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

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

2. Set the playback rate to new playback rate.

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

The procedure to silently set the animation playback rate of animation, animation to new playback rate is identical to the above procedure except that rather than invoking the procedure to set the current time in the final step, the procedure to silently set the current time is invoked instead.

3.5.18. 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 and abort these steps.

2. Silently set the animation playback rate of animation to −animation playback rate.

   This must be done silently or else we may end up resolving the current ready promise when we do the compensatory seek despite the fact that we are most likely not exiting the pending play state.

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

3.5.19. 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.timing.duration = 5000;
animation.currentTime = 4000;
animation.pause();
animation.ready.then(function() {
  animation.effect.timing.duration = 3000;
  alert(animation.playState); // Displays 'paused'
  animation.startTime =
    document.timeline.currentTime - animation.currentTime * animation.playbackRate;
  alert(animation.playState); // Displays 'finished'
});

3.5.20. Animation events

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

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

3.5.20.1. Types of animation 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.

3.5.20.2. Event parameters

Animation events have an associated event current time and event timeline time.

The event current time is the current time of the animation that generated the event at the moment the event is queued. This will be unresolved if the animation was idle at the time the event was generated.

The event timeline time is the time value of the timeline with which the animation that generated the event is associated at the moment the event is queued. This will be unresolved if the animation was not associated with a timeline at the time the event was generated or if the associated timeline was inactive.

3.6. Animation effects

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

3.6.1. Relationship between animation effects and animations

The target effect of an animation, if set, is a type of animation effect. The target 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.

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

3.6.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 §3.9.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).

3.6.4. Local time

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

3.6.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 sample and are primarily a convenience for describing stative parts of the model.

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

in play

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

current

Corresponds to an animation effect that is either in play or may become in play in the future.

This will be the case if the animation effect is in play or in its before phase.

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 §3.7 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.

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 either of the following conditions is true:

• the animation effect is in the before phase, or

• the animation effect is in play.

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

3.7. 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 §3.9.3.1 Calculating the active time.

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

3.8. Repeating

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

3.8.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 §3.9 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.

3.8.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 §3.9.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 active document.

3.8.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 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 target 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 §3.9.3.3 Calculating the simple iteration progress and is illustrated below.

3.9. Core animation effect calculations

3.9.1. Overview

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

3.9.3. Transforming the local time

3.9.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,

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

3.9.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,

   • the animation effect is in the after phase, and

   • iteration count is not equal to zero, and

   • either the active time is not zero or the iteration duration is 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 two conditions prevent this from applying when we never played any iterations of the animation to begin with because either (a) the iteration count was zero, or (b) the playback range of the active interval was clipped to zero using a negative end delay. In detecting if the active interval’s playback range was clipped to zero, we check for a zero active time in the after phase, but if the iteration duration was zero to begin with then we say that the animation was not clipped.

4. Return simple iteration progress.

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

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

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

3.11. Time transformations

3.11.1. Scaling the time

This section is non-normative

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. Conversely, in other situations such as when modeling a discrete change, a smooth transition is undesirable and instead it is necessary for the animation effect to progress in a series of distinct steps.

For such situations Web Animations provides timing functions that scale the progress of an animation effect.

Timing functions take an input progress value and produce a scaled output progress value.

Timing functions are applied to an iteration of an animation effect.

3.11.2. Timing functions

A timing function takes an input progress value in the range [0, 1] and produces an output progress value whose range is unbounded (i.e. positive and negative infinity are permitted).

Animation effects have one timing function associated with them. The default timing function is the linear timing function whose output is identical to its input. The linear timing function can be represented by the string “linear”.

The range of timing functions that may be applied to a given animation effects depends on the type of the animation effects.

3.11.3. Scaling using a cubic Bézier curve

This section is non-normative

A common method of producing easing effects is to use a cubic Bézier curve to scale the time. The endpoints of the curve are fixed at (0, 0) and (1, 1) while two control points P1 and P2 define the shape of the curve. Provided the x values of P1 and P2 lie within the range [0, 1] such a curve produces a function that is used to map input times (the x values) onto output times (the y values). This arrangement is illustrated below.

Some example cubic Bézier timing functions are illustrated below.

A cubic Bézier timing function is a type of timing function defined by four real numbers that specify the two control points, P1 and P2, of a cubic Bézier curve whose end points are fixed at (0, 0) and (1, 1). The x coordinates of P1 and P2 are restricted to the range [0, 1].

The evaluation of this curve is covered in many sources such as [FUND-COMP-GRAPHICS].

A cubic Bézier timing function may be specified as a string using the following syntax (using notation from [CSS3VAL]):

<cubic-bezier-timing-function> = ease | ease-in | ease-out | ease-in-out | cubic-bezier(<number>, <number>, <number>, <number>)

The meaning of each value is as follows:

ease

Equivalent to cubic-bezier(0.25, 0.1, 0.25, 1).

ease-in

Equivalent to cubic-bezier(0.42, 0, 1, 1).

ease-out

Equivalent to cubic-bezier(0, 0, 0.58, 1).

ease-in-out

Equivalent to cubic-bezier(0.42, 0, 0.58, 1).

cubic-bezier(<number>, <number>, <number>, <number>)

Specifies a cubic Bézier timing function. The four numbers specify points P1 and P2 of the curve as (x1, y1, x2, y2). Both x values must be in the range [0, 1] or the definition is invalid.

cubic-bezier( [ <number>{6} ; ]* <number>{4} )

3.11.4. Timing in discrete steps

This section is non-normative It is possible to scale an animation effect’s timing so that the group effect occurs in a series of discrete steps using a stepping function.

Some example step timing functions are illustrated below.

A step timing function is a type of timing function that divides the input time into a specified number of intervals that are equal in duration. The output time, starting at zero, rises by an amount equal to the interval duration once during each interval at the transition point which may be either the start, midpoint, or end of the interval.

In keeping with Web Animations' model of endpoint exclusive interval timing (see §3.8.4 Interval timing), the output time at the transition point is the time after applying the increase (i.e. the top of the step) with the following exception.

When a transition point coincides with the end of the active interval extra care must be taken to produce the correct result when performing a fill. To achieve this, when a step timing function is applied to an animation effect or applied to an keyframe associated with a keyframe effect, an additional before flag is passed. The value of the before flag is determined as follows:

1. If the active time of the animation effect is unresolved, the before flag is not set and these steps should be aborted.

2. Determine the current direction using the procedure defined in §3.10.1 Calculating the directed progress.

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

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

When a step timing function is evaluated at a transition point, if the before flag is set the result is the value before applying the increase.

A step timing function may be specified as a string using the following syntax:

<step-timing-function> = step-start | step-middle | step-end | steps(<integer>[, [ start | middle | end ] ]?)

step-middle and the middle keyword will likely be removed in favor of a frames() timing function.

The meaning of each value is as follows:

step-start

Equivalent to steps(1, start);

step-middle

Equivalent to steps(1, middle);

step-end

Equivalent to steps(1, end);

steps(<integer>[, [ start | middle | end ] ]?)

Specifies a step timing function. The first parameter specifies the number of intervals in the function. It must be a positive integer (greater than 0). The second parameter, which is optional, specifies the point at which the change of values occur within the interval. If the second parameter is omitted, it is given the value end.

3.11.5. 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. Return the result of evaluating the animation effect’s timing function passing directed progress as the input progress.

3.11.6. Calculating the iteration progress

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

4. Animation model

4.1. Introduction

An animation effect may have 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.

4.2. Procedures for animating properties

Unless specifically defined otherwise, all CSS properties are considered animatable. In order to animate a property, the following procedures must be defined.

• interpolation — given two property values V_start and V_end, produces an intermediate value V_result at a distance of p along the interval between V_start and V_end such that p = 0 produces V_start and p = 1 produces V_end. The range of p is (−∞, ∞) due to the effect of timing functions. As a result, this procedure must also define extrapolation behavior for p outside [0, 1].

• addition — given two property values V_a and V_b, returns the sum of the two properties, V_result. For addition that is not commutative (for example, matrix multiplication) V_a represents the first term of the operation and V_b represents the second.

  This section is non-normative

  While addition can often be expressed in terms of the same weighted sum function used to define interpolation, this is not always the case. For example, interpolation of transform matrices involves decomposing and interpolating the matrix components whilst addition relies on matrix multiplication.

• accumulation — given two property values V_a and V_b, returns the result, V_result, of combining the two operands such that V_b is treated as a delta from V_a. For accumulation that is not commutative (for example, accumulation of mismatched transform lists) V_a represents the first term of the operation and V_b represents the second.

  This section is non-normative

  For many types of animation such as numbers or lengths, accumulation is defined to be identical to addition.

  A common case where the definitions differ is for list-based types where addition may be defined as appending to a list whilst accumulation may be defined as component-based addition. For example, the filter list values "blur(2)" and "blur(3)", when added together may produce "blur(2) blur(3)", but when accumulated, may produce "blur(5)".

• distance computation — given two property values V_start and V_end, calculates some notion of scalar distance between the values, distance.

Note that the above procedures apply to CSS computed property values (see §4.4.3 Calculating computed keyframes). As a result, it is not necessary to define, for example, how to add a length value of "15pt" with "5em" since such values will be resolved to pixel values before being passed to any of the above procedures.

4.3. Animation types

The specific procedures used for animating a given property are referred to as the property’s animation type.

The animation type of each CSS property is defined by the "Animatable:" line in the summary of the property’s definition or in [CSS3-TRANSITIONS] for properties that lack a such a line. For custom properties registered using the registerProperty() method for the current global object, the animation type is derived from the type used to define the property’s syntax. Where there is no animation type that corresponds to the property’s specified syntax (e.g. when the syntax is "*") the animation type is discrete. The animation type of all other custom properties is discrete.

The above doesn’t explain the animation type to use for of syntax such as "<length>+". We will fix this once the definition of animation types has moved to CSS Values and Units where we should define generic handling for list types etc.

Following is a series of pre-defined animation types. [CSS3-TRANSITIONS] provides further CSS-specific animation types.

For animation types that do not define a specific procedure for addition or which are defined as not additive, the addition procedure is simply V_res = V_b.

For animation types that do not define a specific procedure for accumulation, the accumulation procedure is identical to the addition procedure for that type.

For animation types that do not define a specific procedure for distance computation or which are defined as not paceable, the distance computation procedure is simply distance = 0.

4.3.1. Not animatable

Some properties are specifically defined as not animatable. For example, properties defining animation parameters are not animatable since doing so would create complex recursive behavior.

Unlike other animation types, no procedures for interpolation, addition and distance computation are defined for properties whose animation type is not animatable since these properties should not be modified.

An animation effect that targets a property that is not animatable will still exhibit the usual behavior for an animation effect such as delaying the fulfilment of an animation’s current finished promise.

4.3.2. Discrete

A property whose animation type is discrete has the following behavior:

• interpolation:

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

  V_result = V_start, if p < 0.5 or V_end, if p ≥ 0.5

4.3.3. Real number

A property whose animation type is real number has the following behavior:

• interpolation: V_result = (1 - p) × V_start + p × V_end

• addition: V_result = V_a + V_b

• distance computation: distance = |V_end - V_start|

4.3.4. Length, percentage, or calc

A property whose animation type is length, percentage, or calc has the following behavior:

• interpolation: as defined in [CSS3-TRANSITIONS].

• addition: V_result = calc(V_a + V_b)
  (Nested calc() functions are expanded when determining the computed value as defined in CSS Values and Units [CSS3VAL].)

• distance computation: as with real number but using the computed value [CSS21] for V_start and V_end.

  This whole section needs to be rewritten to account for when we have lengths and percentages. In short, we don’t expand these to used values since that was deemed overly complex (without compelling use cases) and makes calculating keyframe offsets dependent on layout. So we should probably just use the square distance of each component, despite the fact that it will rarely produce a useful result.

  When there is insufficient context to calculate a computed value for all possible values of V_start and V_end, the result of the distance computation calculation is zero (i.e. the behavior degenerates to not paceable).

  For example, for a keyframe effect that does not have an target element, there is no context for resolving em-based values against. As a result, the following code snippet falls back to not paceable animation type.

  var effect =
    new KeyframeEffect([ { top: '10px' },
                         { top: '20em' },
                         { top: '50em' } ],
                       { spacing: 'paced(top)' });
  // Prints '0, 0.5, 1'
  effect.getKeyframes().map(frame => frame.computedOffset).join(', ');
  

  For consistency, this definition applies even when a computed value could be calculated for each of the animation values in question. As such, the following code fragment produces the same result.

  var effect =
    new KeyframeEffect([ { top: '10px' },
                         { top: '20px' },
                         { top: '50px' } ],
                       { spacing: 'paced(top)' });
  // Prints '0, 0.5, 1'
  effect.getKeyframes().map(frame => frame.computedOffset).join(', ');
  

4.3.5. Color

A property whose animation type is color has the following behavior:

• interpolation: as defined in [CSS3-TRANSITIONS].

• addition: as with real number but performed on each RGBA color component in premultiplied space.

  Note: Since negative color is not currently supported, clamping of the channel values may be performed upon each addition or once when composition is complete.

• distance computation:

  $\mathrm{distance}=\sqrt{{\left(R_{\mathrm{end}}-R_{\mathrm{start}}\right)}^2+{\left(G_{\mathrm{end}}-G_{\mathrm{start}}\right)}^2+{\left(B_{\mathrm{end}}-B_{\mathrm{start}}\right)}^2+{\left(A_{\mathrm{end}}-A_{\mathrm{start}}\right)}^2}$

  distance = sqrt((R_end - R_start)^2 + (G_end - G_start)^2 + (B_end - B_start)^2 + (A_end - A_start)^2)

  where <RGB|A_start|end> represents the red, green, blue, or alpha channel of V_start or V_end respectively. Each value is normalized to the [0.0, 1.0] range and expressed in premultiplied color space.

4.3.6. Transform list

A property whose animation type is transform list has the following behavior:

• interpolation: as defined in Interpolation of Transforms [CSS3-TRANSFORMS].

• addition: performed by concatenating transform lists as ‘V_a V_b’.

• accumulation:

  1. Beginning at the end of each list, V_a and V_b, find the largest contiguous portion of each list where the corresponding list elements from each list have the same transform type. Call the matching portions from V_a and V_b, V_matching-a and V_matching-b respectively and likewise V_remainder-a and V_remainder-b for the non-matching parts.

     We should probably expand 2d functions to their 3d equivalents before matching?

  2. Let V_combined be a transform list combining V_matching-a and V_matching-b by adding the numeric components of each corresponding function.

     This needs to be more specific, e.g. when combining translate(20px) and translate(30px 10px) we have to expand the first function to translate(20px 0px) first. Probably need to define unit conversion too.

  3. The result of accumulation is a transform list created by adding the combined result with the non-matching portions of the two lists as follows: ‘V_remainder-a V_remainder-b V_combined’.

• distance computation: See issue below.

4.3.7. Other animation types

The set of animation types defined here may be extended by other specifications. For example, properties with using the <image> type are animated using the interpolation behavior defined in CSS Image Values and Replaced Content [CSS3-IMAGES].

4.4. Keyframe effects

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

4.4.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 §4.4.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 also have a keyframe-specific composite operation that 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 §4.5.4 Effect composition. If no keyframe-specific composite operation is specified for a keyframe, the composite operation specified for the keyframe effect as a whole is used for values specified in that keyframe.

4.4.2. Spacing keyframes

This section is non-normative.

It is often useful to be able to provide a series of property values without having calculate the keyframe offset of each value in time but instead to rely on some automatic spacing.

For example, rather than typing:

elem.animate([ { color: 'blue', offset: 0 },
               { color: 'green', offset: 1/3 },
               { color: 'red', offset: 2/3 },
               { color: 'yellow', offset: 1 } ], 2000);

It should be possible to type the following and allow the user agent to calculate the offset of each keyframe:

elem.animate([ { color: 'blue' },
               { color: 'green' },
               { color: 'red' },
               { color: 'yellow' } ], 2000);

Web Animations provides spacing modes for this purpose. The default spacing mode for keyframe effects is “distribute” which produces the result described above.

The other spacing mode, “paced”, is useful when it is desirable to maintain an even rate of change such as for motion path animation.

For example, consider the following animation:

elem.animate([ { left: '0px' },
               { left: '-20px' },
               { left: '100px' },
               { left: '50px' } ], 1000);

The resulting value of the left property is illustrated below:

We can use the paced spacing mode as follows:

elem.animate([ { left: '0px' },
               { left: '-20px' },
               { left: '100px' },
               { left: '50px' } ],
             { duration: 1000, spacing: "paced(left)" });

The result is illustrated below:

It is also possible to combine fixed keyframe offsets with spacing modes as follows:

elem.animate([ { left: '0px' },
               { left: '-20px' },
               { left: '100px', offset: 0.5 },
               { left: '50px' } ],
             { duration: 1000, spacing: "paced(left)" });

The result is illustrated below:

Before calculating effect values from a keyframe effect, an absolute value must be computed for the keyframe offset of each keyframe with a null offset.

The values computed depend on the keyframe spacing mode specified for the keyframe effect. The keyframe spacing modes are:

distribute

Indicates that keyframes with a null keyframe offset are positioned so that the difference between subsequent keyframe offsets are equal.

paced

Indicates that keyframes with a null keyframe offset are positioned so that the distance between subsequent values of a specified paced property are equal. The distance is calculated using the distance computation procedure defined by the animation type associated with the paced property.

Since the absolute value calculated for a keyframe offset may change depending on the keyframe values, the number of values, or external context (such as when using paced keyframe spacing mode in combination with em-based units), the original null values are not overwritten but rather, the calculated absolute values are stored as a separate value on each keyframe known as its computed keyframe offset.

4.4.2.1. Applying spacing to keyframes

We define a generic procedure for evenly distributing a keyframe, keyframe, between two reference keyframes, start and end, whose computed keyframe offsets are not null, 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 start and end minus 1.

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

4. Set the computed keyframe offset of keyframe to offset_start + (offset_end − offset_start) × index / n.

The procedure to apply spacing to a series of keyframes takes the following parameters:

• a sequence of keyframes: keyframes,

• a spacing mode, spacing, and

• a context element used for resolving relative units, context element, (only required when spacing is paced)

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 depending on the value of spacing as follows:

   If spacing is paced,

   1. Define a keyframe as paceable if it contains a value for the paced property.

   2. Let paced A be the first keyframe in the range [A, B] that is paceable, if any.

   3. Let paced B be the last keyframe in the range [A, B] that is paceable, if any.

   4. If there is no paced A or paced B let both refer to B.

      Note: In this case the spacing behavior degenerates to distribute spacing.

   5. For each keyframe in the range (A, paced A] and [paced B, B), apply the procedure for evenly distributing a keyframe using A and B as the start and end keyframes respectively.

      Yes, this is correct. We want, index and n in that procedure to reflect all the keyframes between A and B, not just the keyframes between, for example, A and paced A.

   6. For each keyframe in the range (paced A, paced B) that is paceable:

      1. Let dist_k represent the cumulative distance to a keyframe k from paced A as calculated by applying the distance computation defined by the animation type of the paced property to the values of the paced property on each pair of successive paceable keyframes in the range [paced A, k]. Use context element as the basis for resolving context-sensitive values such as font-size based units.

      2. Set the computed keyframe offset of k to offset_{paced A} + (offset_{paced B} − offset_{paced A}) × dist_k / dist_{paced B}. If dist_{paced B} is zero, leave the computed keyframe offset as null—it will be set in the next step when we apply distribute spacing to remaining keyframes.

   7. For each keyframe in the range (paced A, paced B) that still has a null computed keyframe offset (because it is not paceable, or because the cumulative distance between paceable properties was zero), apply the procedure for evenly distributing a keyframe using the nearest keyframe before and after the keyframe in question in keyframes that has a computed keyframe offset that is not null, as the start and end keyframes respectively.

   Otherwise,

   Apply the procedure for evenly distributing a keyframe to each keyframe in the range (A, B) using A and B as the start and end keyframes respectively.

4.4.3. Calculating computed keyframes

Before calculating the effect value of a keyframe effect, we must resolve specified property values to computed values and applying spacing to compute absolute values for the keyframe offset of each keyframe with a null offset. The result of resolving these values is a set of computed keyframes.

Computed keyframes are produced using the following procedure. Note that this procedure is only performed on a keyframe effect having a target element 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, calculate the computed value specified on keyframe using the target element as the context for computing values and add the corresponding property and computed value to computed keyframe. For shorthand properties, add the equivalent longhand properties.

      For example, if keyframe has a value of ‘12pt’ for the border-width property, the user agent may produce a computed 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 computed value, ‘16px’.

      If conflicts arise when expanding shorthand properties due to shorthand properties overlapping with existing longhand properties or other with other shorthand 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. 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.

      NOTE: Invalid property values and values unsupported by the implementation MUST be preserved such that when spacing is applied later in this procedure, the keyframes are spaced as if the value was supported.

3. Perform the procedure to apply spacing to a series of keyframes on computed keyframes using the keyframe spacing mode for this effect as spacing, and the target element for this effect as the context element.

4. Return computed keyframes.

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

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

6. Remove any keyframes from property-specific keyframes that do not have a property value for target property or for which the property value is invalid or unsupported by the implementation.

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

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

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

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

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

12. 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 composite operation to use procedure defined by the target property’s animation type.

    2. If this keyframe effect has an iteration composite operation of accumulate, apply the following step current iteration times:

       • replace the property value of target property on keyframe with the result of combining the property value (V_a) with the property value on the final keyframe in property-specific keyframes (V_b) using the accumulation procedure defined for target property.

       It seems like this could be done as a separate step at the end and applied to all types of animation effects consistently.

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

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

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

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

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

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

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

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

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

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

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

4.5.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 §4.5.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 §4.5.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.

4.6. Effect accumulation

Similar to the compositing performed between effect values (see §4.5.4 Effect composition), the iteration composite operation determines how values are combined between successive iterations of the same keyframe effect.

This specification defines two iteration composite operations as follows:

replace

Each successive iteration is calculated independently of previous iterations.

accumulate

Successive iterations of the animation are accumulated with the final value of the previous iteration.

The application of the iteration composite operation is incorporated in the calculation of the effect value in §4.4.4 The effect value of a keyframe effect.

4.7. Side effects of animation

For every property targeted by at least one animation effect that is current or in effect, the user agent must act as if the will-change property ([css-will-change-1]) on the target element includes the property.

5. Programming interface

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

5.2. The AnimationTimeline interface

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

interface AnimationTimeline {
    readonly attribute double? currentTime;
};

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

[Constructor (optional DocumentTimelineOptions options)]
interface DocumentTimeline : AnimationTimeline {
};

5.4. The Animation interface

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

[Constructor (optional AnimationEffectReadOnly? effect = null,
              optional AnimationTimeline? timeline)]
interface Animation : EventTarget {
             attribute DOMString                id;
             attribute AnimationEffectReadOnly? effect;
             attribute AnimationTimeline?       timeline;
             attribute double?                  startTime;
             attribute double?                  currentTime;
             attribute double                   playbackRate;
    readonly attribute AnimationPlayState       playState;
    readonly attribute Promise<Animation>       ready;
    readonly attribute Promise<Animation>       finished;
             attribute EventHandler             onfinish;
             attribute EventHandler             oncancel;
    void cancel ();
    void finish ();
    void play ();
    void pause ();
    void reverse ();
};

5.4.1. The AnimationPlayState enumeration

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

idle

Corresponds to the idle play state.

pending

Corresponds to the pending play state.

running

Corresponds to the running play state.

paused

Corresponds to the paused play state.

finished

Corresponds to the finished play state.

5.5. The AnimationEffectReadOnly interface

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

interface AnimationEffectReadOnly {
    readonly attribute AnimationEffectTimingReadOnly timing;
    ComputedTimingProperties getComputedTiming();
};

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 from its animation?

5.6. The AnimationEffectTimingReadOnly interface

This interface needs a constructor.

interface AnimationEffectTimingReadOnly {
    readonly attribute double                             delay;
    readonly attribute double                             endDelay;
    readonly attribute FillMode                           fill;
    readonly attribute double                             iterationStart;
    readonly attribute unrestricted double                iterations;
    readonly attribute (unrestricted double or DOMString) duration;
    readonly attribute PlaybackDirection                  direction;
    readonly attribute DOMString                          easing;
};

5.7. The AnimationEffectTiming interface

The AnimationEffectTiming interface is a mutable subclass of AnimationEffectTimingReadOnly returned for the timing attribute of a mutable animation effect such as KeyframeEffect.

This interface needs a constructor.

interface AnimationEffectTiming : AnimationEffectTimingReadOnly {
    inherit attribute double                             delay;
    inherit attribute double                             endDelay;
    inherit attribute FillMode                           fill;
    inherit attribute double                             iterationStart;
    inherit attribute unrestricted double                iterations;
    inherit attribute (unrestricted double or DOMString) duration;
    inherit attribute PlaybackDirection                  direction;
    inherit attribute DOMString                          easing;
};

5.8. The AnimationEffectTimingProperties dictionary

The AnimationEffectTimingProperties dictionary encapsulates the timing properties of an AnimationEffectReadOnly so that they can be set in bulk (as with the Animation() constructor) or returned as a readonly snapshot (as with the getComputedTiming() method of the AnimationEffectReadOnly interface).

AnimationEffectTimingProperties is simply a dictionary-equivalent of the AnimationEffectTiming interface. The meaning and acceptable values for each of its members are identical.

dictionary AnimationEffectTimingProperties {
    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";
};

5.9. The ComputedTimingProperties dictionary

Timing parameters calculated by the timing model are exposed using ComputedTimingProperties dictionary objects.

dictionary ComputedTimingProperties : AnimationEffectTimingProperties {
    unrestricted double  endTime;
    unrestricted double  activeDuration;
    double?              localTime;
    double?              progress;
    unrestricted double? currentIteration;
};

5.9.1. 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 will produce different behavior for other types of animation effects.

5.9.2. 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 way they are specified.

alternate

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

alternate-reverse

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

5.10. The KeyframeEffectReadOnly and KeyframeEffect interfaces

Keyframe effects are represented by the KeyframeEffectReadOnly interface. Mutable keyframe effects are represented by the KeyframeEffect interface.

[Constructor (Animatable? target,
              object? keyframes,
              optional (unrestricted double or KeyframeEffectOptions) options),
 Constructor (KeyframeEffectReadOnly source)]
interface KeyframeEffectReadOnly : AnimationEffectReadOnly {
    readonly attribute Animatable?                 target;
    readonly attribute IterationCompositeOperation iterationComposite;
    readonly attribute CompositeOperation          composite;
    readonly attribute DOMString                   spacing;
    sequence<object> getKeyframes ();
};

[Constructor (Animatable? target,
              object? keyframes,
              optional (unrestricted double or KeyframeEffectOptions) options),
 Constructor (KeyframeEffectReadOnly source)]
interface KeyframeEffect : KeyframeEffectReadOnly {
    inherit attribute Animatable?                 target;
    inherit attribute IterationCompositeOperation iterationComposite;
    inherit attribute CompositeOperation          composite;
    inherit attribute DOMString                   spacing;
    void setKeyframes (object? keyframes);
};

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

5.10.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. 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. Otherwise, return the result of applying the IDL attribute to CSS property algorithm [CSSOM] to attribute.

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

// An SVG-style to-animation
elem.animate([ { left: '0px', composite: 'add' },
               { left: '200px' } ], 2000);

// Each keyframe can have a different timing function.
// The timing function specified for the last keyframe is not used.
elem.animate([ { color: 'blue', easing: 'ease-in' },
               { color: 'green', easing: 'ease-out' },
               { color: 'yellow' } ], 2000);

// Each keyframe will have a timing function of 'ease-in-out'
elem.animate({ color: [ 'blue', 'green', 'yellow' ],
               easing: 'ease-in-out' }, 2000);

dictionary Keyframe {
    // ... property-value pairs ...
    // i.e. DOMString propertyName
    double?             offset = null;
    DOMString           easing = "linear";
    CompositeOperation  composite;
};

dictionary PropertyIndexedKeyframes {
    // ... property-value and property-valuelist pairs ...
    // i.e. (DOMString or sequence<DOMString>) propertyName
    DOMString           easing = "linear";
};

typedef (sequence<Keyframe> or
         PropertyIndexedKeyframes or
         SharedKeyframeList) 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 {
       DOMString          easing = "linear";
       CompositeOperation composite;
   };
   

   Otherwise,

   Use the following dictionary type,

   dictionary BaseKeyframe {
       double?            offset = null;
       DOMString          easing = "linear";
       CompositeOperation composite;
   };
   

   Do we need null offsets or is it enough to just test for the absence of the property?

   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 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 either a sequence of keyframes or a SharedKeyframeList object using the following procedure:

1. If object is null, return an empty sequence of keyframes.

2. If object is a platform object that implements SharedKeyframeList, return object.

3. Let processed keyframes be an empty sequence of keyframes.

4. Let method be the result of GetMethod(object, @@iterator).

5. Check the completion record of method.

6. 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 nextItem is not an object, 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.

   4. If processed keyframes is not loosely sorted by offset, throw a TypeError and abort these steps.

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

   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. Let easing be the value of the “easing” member of property-indexed keyframe.

   3. 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” 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. Let k have a property, “easing” with the value of easing.

         3. Add the property-value pair, property name → v, to k.

         4. Append k to property keyframes.

      6. Apply the procedure to apply spacing to a series of keyframes to property keyframes using a spacing mode of distribute.

         We unconditionally apply distribute spacing simply for the purposes of merging keyframes. This produces consistent and intuitive results.

         Paced spacing can produce different results depending on the context in which relative values are resolved. Using paced spacing to calculate offsets and then merging would mean that the merge results could differ over time. It would also mean that the keyframes returned from getKeyframes() would produce a different result if passed back to setKeyframes() since the merge result which, until that point, was dynamic, would suddenly become fixed.

         Due to these considerations we apply merging once when updating the keyframes using distribute spacing which does not vary in its results.

         Before computing the effect result or returning keyframes from getKeyframes() the specified spacing mode is applied.

      7. Add keyframes in property keyframes to processed keyframes.

   4. Sort processed keyframes by the computed keyframe offset of each keyframe in increasing order.

   5. Merge adjacent keyframes in processed keyframes when they have equal computed keyframe offsets.

7. 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, store the original DOMString used for the property value.

      User agents that provide support for diagnosing errors in content SHOULD produce an appropriate warning highlighting the unrecognized 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 property of the AnimationEffectTimingReadOnly interface.

      If parsing the “easing” property fails, let the timing function of frame be “linear”.

      User agents that provide support for diagnosing errors in content SHOULD produce an appropriate warning highlighting the unrecognized timing function in this case.

      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.

5.10.4. The KeyframeEffectOptions dictionary

Additional parameters may be passed to the KeyframeEffectReadOnly(target, keyframes, options) and KeyframeEffect(target, keyframes, options) constructors by providing a KeyframeEffectOptions object.

dictionary KeyframeEffectOptions : AnimationEffectTimingProperties {
    IterationCompositeOperation iterationComposite = "replace";
    CompositeOperation          composite = "replace";
    DOMString                   spacing = "distribute";
};

5.10.5. Computed-offset keyframes

The set of keyframes returned by getKeyframes() is based on the specified keyframes for the keyframe effect (i.e. the result of running the process a keyframes argument procedure) but also includes the offsets from the computed keyframes. This combined result is referred to as the computed-offset keyframes and, for KeyframeEffect effect, is produced as follows:

1. Let computed-offset keyframes be a copy of the keyframes specified for effect.

2. If there is a target element specified for effect that can be used to calculate CSS computed values, perform the following steps.

   1. Let computed keyframes be the result of calculating the computed keyframes for effect.

   2. Copy the computed keyframe offset values from computed keyframes to their corresponding keyframes in computed-offset keyframes.

   Otherwise, if there is no target element specified for effect, or the target element is not able to be used to calculate CSS computed values, perform the following steps:

   1. Apply the procedure to apply spacing to a series of keyframes to computed-offset keyframes using a spacing mode of distribute.

3. Return computed-offset keyframes.

This procedure needs to be updated to correctly return a SharedKeyframeList object when specified. This is currently deferred since SharedKeyframeList is awaiting implementation experience.

5.11. The IterationCompositeOperation enumeration

The possible values of an animation effect’s iteration composite operation are represented by the IterationCompositeOperation enumeration.

enum IterationCompositeOperation {"replace", "accumulate"};

replace

Corresponds to the replace iteration composite operation value such that the effect value produced is independent of the current iteration.

accumulate

Corresponds to the accumulate iteration composite operation value such that subsequent iterations of an animation effect build on the final value of the previous iteration.

5.12. The CompositeOperation enumeration

The possible values of an animation effect’s composition behavior are represented by the CompositeOperation enumeration.

enum CompositeOperation {"replace", "add", "accumulate"};

replace

Corresponds to the replace composite operation value such that the animation effect overrides the underlying value it is combined with.

add

Corresponds to the add composite operation value such that the animation effect is added to the underlying value with which it is combined.

accumulate

Corresponds to the accumulate composite operation value such that the animation effect is accumulated on to the underlying value.