Web Animations

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

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

Make animation’s previous current time unresolved.

4.5.5. Setting the start time of an animation

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

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

4.5.6. Waiting for the associated effect

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

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

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

4.5.7. The current ready promise

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

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

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

4.5.8. Playing an animation

Resolve animation’s current ready promise with animation.

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: The order of the above two steps is important since it means that an animation with zero-length associated effect will resolve its current ready promise before its current finished promise.

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

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

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

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

4.5.9. Pausing an animation

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

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

4.5.10. Reaching the end

This section is non-normative

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

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

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

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

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

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

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

4.5.11. The current finished promise

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

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

4.5.12. Updating the finished state

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

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

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

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

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

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

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

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

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

4.5.13. Finishing an animation

4.5.14. Canceling an animation

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

4.5.15. Speed control

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

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

4.5.15.1. Setting the playback rate of an animation

4.5.15.2. Seamlessly updating the playback rate of an animation

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

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

Initially the pending playback rate of an animation is unset.

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

4.5.16. Reversing an animation

4.5.17. Play states

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

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

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

4.5.18. Animation events

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

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

4.5.18.1. Sorting animation events

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

4.5.18.2. Animation playback events

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

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

4.5.18.3. Types of animation playback events

finish

Queued whenever an animation enters the finished play state.

cancel

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

remove

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

4.6. Animation effects

An animation effect is a timing node that provides a static description of some timed behavior.

All animation effects have the following properties:

• an active interval, determined by its start delay and active duration, defining the time interval during which its behavior takes effect

• an iteration duration, iteration count, and iteration start defining how its behavior repeats within that interval

• a playback direction applying to each iteration, to allow reversing the timing of effects within an iteration

• a fill mode defining the application of effects before/after its active interval

• optionally, an associated animation and through it, optionally, an associated timeline, which cause the animation effect to apply its behavior by driving its local time value

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

4.6.2. Associated animation and timeline

An animation effect is associated with an animation when the effect is that animation’s associated effect. At a given moment, an animation effect can be associated with at most one animation.

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

4.6.3. Local time

The local time of an animation effect represents the current time provided by its associated animation, determining the progress of the animation effect. At a given moment, it is based on the first matching condition below:

4.6.4. Time spaces

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.

Within the Web Animations model we define progress of an animation effect on the basis of its active time, which is a time relative to the beginning of its active interval—​thus a time in the active time space.

Note: This time space is internal to the model and not exposed in the programming interface or in markup.

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

The animation effect thus translates the current time provided by the associated animation through a series of time spaces:

• the local time space, relative to the start time of the associated animation, yielding the local time

• the active time space, relative to the start of the active interval, yielding the active time

• the iteration time space, relative to the start of the animation effect’s current iteration, yielding the iteration time

These time spaces are illustrated below.

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

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

4.6.5. The active interval

Animation effects define an active interval, which is the period of time during which the effect is scheduled to produce its effect (excepting fill modes, which apply outside the active interval). Each animation effect has only one such interval, which is defined by its start delay and active duration.

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

4.6.5.1. The start delay

The lower bound of the active interval by default corresponds to the start time of the associated animation, but can be shifted by the start delay, which is a signed offset from the start time of the animation.

4.6.5.2. The active duration

The length of the active interval is called the active duration, and is determined by the iteration duration and iteration count as defined below. Its length determines the upper bound of the active interval.

active duration = iteration duration × iteration count

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

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

4.6.5.3. The end delay and animation effect end time

Similar to the start delay, an animation effect also has an end delay, which is primarily of use when sequencing one animation effect based on the end time of another animation effect.

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

Note: Although the end delay 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).

4.6.6. Animation effect phases and states

This section is non-normative

At a given moment, an animation effect can 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 can also be described as being in one of several overlapping states. These states are only established for the duration of a single animation frame and are primarily a convenience for describing stative parts of the model.

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

in play

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

current

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

in effect

Corresponds to an animation effect that has a resolved active time. This occurs when either the animation effect is in its active phase or outside the active phase but at a time where the effect’s fill mode (see § 4.6.8 Fill behavior and fill modes) 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.

The phase of an animation effect depends on 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 “forward”.

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:

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

• 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:

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

• 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 neither in the before phase nor in the after phase.

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

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

• the animation effect is in the active phase, and

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

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

• the animation effect is in play, or

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

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

• the animation effect is associated with an animation not in the idle play state with a non-null associated timeline that is not monotonically increasing.

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

4.6.7. Relevant animations

We can define an animation as being relevant based on the animation effect associated with it.

An animation is relevant if:

• Its associated effect is current or in effect, and

• Its replace state is not removed.

4.6.8. Fill behavior and fill modes

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

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.

The normative effect of these modes is incorporated in the calculation of the active time in § 4.7.2 Calculating the active time.

Some examples of these fill modes are illustrated below.

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

Where possible, authors should set the final state of the animation directly in specified styles.

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

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

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

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

4.6.9. Repeating

4.6.9.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 can be longer or shorter than the iteration duration.

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

4.6.9.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 can also be positive infinity to represent that the animation effect repeats indefinitely.

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

The behavior of these parameters is defined in the calculations in § 4.7 Calculating progress.

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 affect the length of the active duration.

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

4.6.9.3. Interval timing

This section is non-normative

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

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

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

4.6.10. Direction control

Animation effects can 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

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.

The semantics of these values are incorporated into the calculation of the directed progress in § 4.7.6 Calculating the directed progress.

4.6.11. Easing (effect timing transformations)

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

Animation effects each have an effect easing function, which is an easing function used to transform progress across the entirety of each iteration. See § 4.7.7 Calculating the transformed progress.

The default effect easing function is the linear easing function.

Note: Specific types of animation effects may provide additional time transformations. For example, keyframe effects can provide keyframe-specific easing functions that can apply an easing function specifically between two adjacent keyframes.

4.7. Calculating progress

4.7.1. Overview

This section is non-normative

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

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

This process is illustrated below.

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

The first step, calculating the local time is described in § 4.6.3 Local time. Steps 2 to 6 in the diagram are described in the following sections.

4.7.2. Calculating the active time

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

If the animation effect is in the before phase,

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

If the fill mode is backwards or both,

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

Otherwise,

Return an unresolved time value.

If the animation effect is in the active phase,

Return the result of evaluating local time − start delay.

If the animation effect is in the after phase,

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

If the fill mode is forwards or backwards,

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

Otherwise,

Return an unresolved time value.

Otherwise (the local time is unresolved),

Return an unresolved time value.

4.7.3. 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 below:

   If the iteration duration is zero,

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

   Otherwise,

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

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

4.7.4. 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 easing functions applied to the effect, and is calculated as follows:

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

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

3. If all of the following conditions are true:

   • the simple iteration progress calculated above is zero, and

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

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

   • the iteration count is not equal to zero.

   Let the simple iteration progress be 1.0.

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

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

4. Return simple iteration progress.

4.7.5. Calculating the current iteration index

The current iteration index can be calculated using the following steps:

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

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

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

4. Otherwise, return floor(overall progress).

4.7.6. 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 (the playback direction is alternate or alternate-reverse)p,

   1. Let d be the current iteration index.

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

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

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

   Otherwise, return 1.0 − simple iteration progress.

4.7.7. Calculating the transformed progress

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

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

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

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

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

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

3. Return the result of evaluating the effect easing function passing directed progress as the input progress value and before flag as the before flag.

4.7.8. Yielding the iteration progress

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

5. Animation model

5.1. Introduction

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

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

5.2. Animating properties

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

not animatable

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

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

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

discrete

The property’s values cannot be meaningfully combined, thus it is not additive. Interpolation swaps from V_a to V_b at 50% (p=0.5), i.e.

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

by computed value

Corresponding individual components of the computed values are combined (interpolated, added, or accumulated) using the indicated procedure for that value type (see CSS Values 4 § 3 Combining Values: Interpolation, Addition, and Accumulation). If the number of components or the types of corresponding components do not match, or if any component value uses discrete animation and the two corresponding values do not match, then the property values combine as discrete.

repeatable list

Same as by computed value except that if the two lists have differing numbers of items, they are first repeated to the least common multiple number of items. Each item is then combined by computed value. If a pair of values cannot be combined or if any component value uses discrete animation, then the property values combine as discrete.

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

(See prose)

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

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

5.2.1. Custom Properties

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

5.3. Keyframe effects

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

The effect target is comprised of an Element known as the target element and a pseudo-element selector known as the target pseudo-selector. If the effect target is an Element, the target element is that element and the target pseudo-selector is null. If the effect target is a pseudo-element, the target element is its originating element and the target pseudo-selector is one that specifies that particular pseudo-element.

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

5.3.1. Keyframes

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

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

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

Each keyframe also has a keyframe-specific easing function associated with it, which is an easing function that is applied to the period of time between the keyframe on which it is specified and the next keyframe in the list.

Note: The easing function specified on the last keyframe in the list is never applied.

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

5.3.2. Computing property values

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

5.3.3. Calculating computed keyframes

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

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

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

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

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

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

   2. For each property specified in keyframe:

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

      • For shorthand properties, add the equivalent longhand properties.

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

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

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

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

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

      3. Physical properties override logical properties.

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

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

4. Return computed keyframes.

5.3.4. The effect value of a keyframe effect

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

1. If iteration progress is unresolved abort this procedure.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    Otherwise,

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

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

13. For each keyframe in interval endpoints:

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

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

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

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

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

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

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

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

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

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

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

5.4. Combining effects

This section is non-normative

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

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

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

The arrangement is illustrated below:

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

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

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

5.4.1. Animation classes

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

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

5.4.2. The effect stack

An effect stack is associated with each property targeted by one or more keyframe effects. The effect stack establishes the relative composite order of 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. 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 as 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 the position of their associated animations in the global animation list.

Animation effects that sort earlier have lower composite order.

5.4.3. Calculating the result of an effect stack

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

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

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

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

5.4.4. Effect composition

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

This specification defines three composite operations as follows:

replace

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

add

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

accumulate

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

5.4.5. Applying the composited result

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

The level of the cascade to which this specified value is added depends on the class of the animation associated with the effect with the highest composite order in the effect stack for a given property. By default, the specified value is added to the Animation Origin 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 finding the computed value for that property in the absence of animations.

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

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

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

5.5. Replacing animations

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

5.5.1. Replace state

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

• active

• removed

• persisted

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

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

5.5.2. Removing replaced animations

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

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

• The animation's play state is finished.

• The animation's replace state is not removed.

• The animation is associated with a monotonically increasing timeline.

• The animation has an associated effect.

• The animation's associated effect is in effect.

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

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

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

• is replaceable, and

• has a replace state of active, and

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

perform the following steps:

1. Set animation’s replace state to removed.

2. Create an AnimationPlaybackEvent, removeEvent.

3. Set removeEvent’s type attribute to remove.

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

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

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

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

5.6. Side effects of animation

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

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

6. Programming interface

6.1. Time values in the programming interface

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

6.2. The AnimationTimeline interface

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

[Exposed=Window]
interface AnimationTimeline {
  readonly attribute double? currentTime;
};

6.3. The DocumentTimeline interface

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

dictionary DocumentTimelineOptions {
  DOMHighResTimeStamp originTime = 0;
};

[Exposed=Window]
interface DocumentTimeline : AnimationTimeline {
  constructor(optional DocumentTimelineOptions options = {});
};

6.4. The Animation interface

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

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

6.4.1. The AnimationPlayState enumeration

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

idle

Corresponds to the idle play state.

running

Corresponds to the running play state.

paused

Corresponds to the paused play state.

finished

Corresponds to the finished play state.

6.4.2. The AnimationReplaceState enumeration

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

active

Corresponds to the active replace state.

removed

Corresponds to the removed replace state.

persisted

Corresponds to the persisted replace state.

6.5. The AnimationEffect interface

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

[Exposed=Window]
interface AnimationEffect {
    EffectTiming         getTiming();
    ComputedEffectTiming getComputedTiming();
    undefined            updateTiming(optional OptionalEffectTiming timing = {});
};

Note: In future, we may expose any onupdate (double? progress, double currentIteration, Animatable? target, any underlyingValue) so that the animation effects can be driven apart from the timing model.

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

6.5.1. The EffectTiming and OptionalEffectTiming dictionaries

The EffectTiming dictionary represents the timing properties of an AnimationEffect.

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

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

dictionary OptionalEffectTiming {
  double                             delay;
  double                             endDelay;
  FillMode                           fill;
  double                             iterationStart;
  unrestricted double                iterations;
  (unrestricted double or DOMString) duration;
  PlaybackDirection                  direction;
  DOMString                          easing;
};

6.5.2. The FillMode enumeration

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

Represents an animation effect’s fill mode.

none

No fill. (Fill mode none.)

forwards

Fill forwards.

backwards

Fill backwards.

both

Fill both backwards and forwards.

auto

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

6.5.3. The PlaybackDirection enumeration

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

normal

All iterations are played as specified.

reverse

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

alternate

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

alternate-reverse

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

6.5.4. Updating the timing of an AnimationEffect

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

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

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

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

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

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

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

   • delay → start delay

   • endDelay → end delay

   • fill → fill mode

   • iterationStart → iteration start

   • iterations → iteration count

   • duration → iteration duration

   • direction → playback direction

   • easing → easing function

6.5.5. The ComputedEffectTiming dictionary

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

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

6.6. The KeyframeEffect interface

Keyframe effects are represented by the KeyframeEffect interface.

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

6.6.1. Creating a new KeyframeEffect object

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

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

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

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

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

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

6.6.2. Property names and IDL names

6.6.3. Processing a keyframes argument

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

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

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

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

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

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

// The following produces the same result.
elem.animate({ color: [ 'blue', 'green', 'yellow' ],
               easing: [ 'ease-in', 'ease-out' ] }, 2000);

// The repeating behavior makes assigning the same value to all keyframes
// simple:
elem.animate({ color: [ 'blue', 'green', 'yellow' ],
               easing: 'ease-in-out' }, 2000);

// Here, 'ease-in-out' is applied between each color value.
elem.animate({ color: [ 'blue', 'green', 'yellow' ],
               easing: 'ease-in-out' }, 2000);

// However, in this case, 'ease-in-out' is applied across the whole span
// of the animation, that is from 'blue' to 'yellow'.
elem.animate({ color: [ 'blue', 'green', 'yellow' ] },
             { duration: 2000, easing: 'ease-in-out' });

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

dictionary PropertyIndexedKeyframes {
  // ... property-value and property-valuelist pairs ...
  // i.e. (DOMString or sequence<DOMString>) propertyName
  (double? or sequence<double?>)                         offset = [];
  (DOMString or sequence<DOMString>)                     easing = [];
  (CompositeOperationOrAuto or sequence<CompositeOperationOrAuto>) composite = [];
};

typedef (sequence<Keyframe> or PropertyIndexedKeyframes) KeyframeArgument;

For each method that takes a keyframes argument, the procedure to process a keyframes argument is run on the input and the result of that procedure is retained.

First we define two supporting definitions: