<style>

.informative-bg {

margin: 1.5em 0 1em;

padding: 1em;

margin-top: 1em;

background: #efe;

border: green 1px dotted;

}

@media (prefers-color-scheme: dark) {

.informative-bg {

background: rgba(255, 255, 255, .05);

}

}

div.informative-bg *:last-child {

margin-bottom: 0;

}

div.informative-bg p:first-child {

margin-top: 0;

}

div.informative-bg h2,

div.informative-bg h3,

div.informative-bg h4 {

background: none;

}

.attributes::before, .methods::before,

.parameters::before, .exceptions::before,

.constructors::before, .members::before {

font: bold 100% sans-serif;

text-align: left;

margin: 1.33em 0px;

color: var(--heading-text, #005A9C);

}

.attributes::before { content: 'Attributes' }

.methods::before { content: 'Methods' }

.parameters::before { content: 'Parameters' }

.exceptions::before { content: 'Exceptions' }

.constructors::before { content: 'Constructors' }

.members::before { content: 'Dictionary members' }

.param,

.exceptionname,

.estype,

.esvalue {

font-weight: bold;

}

.formula {

display: block;

margin: .5em 2em;

}

</style>

<pre class=metadata>

Title: Web Animations Module Level 1

Group: CSSWG

Shortname: web-animations

Status: ED

Level: 1

Work Status: Refining

ED: https://drafts.csswg.org/web-animations-1/

TR: https://www.w3.org/TR/web-animations-1/

Previous version: https://www.w3.org/TR/2023/WD-web-animations-1-20230605/

Previous version: https://www.w3.org/TR/2021/WD-web-animations-1-20220908/

Previous version: https://www.w3.org/TR/2021/WD-web-animations-1-20210518/

Previous version: https://www.w3.org/TR/2018/WD-web-animations-1-20181011/

Previous version: https://www.w3.org/TR/2016/WD-web-animations-1-20160913/

Previous version: https://www.w3.org/TR/2015/WD-web-animations-1-20150707/

Previous version: https://www.w3.org/TR/2014/WD-web-animations-20140605/

Previous version: https://www.w3.org/TR/2013/WD-web-animations-20130625/

Version history: https://github.com/w3c/csswg-drafts/commits/main/web-animations-1

Editor: Brian Birtles 43194, Invited Expert, [email protected]

Editor: Robert Flack 98451, Google, [email protected]

Editor: Stephen McGruer 96463, Google, [email protected]

Editor: Antoine Quint 51377, Apple Inc, [email protected]

Former Editor: Shane Stephens 47691, Google, [email protected]

Former Editor: Douglas Stockwell, Google, [email protected]

Former Editor: Alex Danilo 31960, Google, [email protected]

Former Editor: Tab Atkins 42199, Google, [email protected]

Abstract: This specification defines a model for synchronization and timing

of changes to the presentation of a Web page.

It also defines an application programming interface (API)

for interacting with this model

and it is expected that other specifications will define

declarative means for exposing these features.

!Participate: <a href="https://github.com/w3c/csswg-drafts/tree/main/web-animations-1">Fix the text through GitHub</a>

!Participate: Join the "waapi" channel on the <a href="https://damp-lake-50659.herokuapp.com/">Animation at Work</a> slack

!Participate: IRC: <a href="ircs://irc.w3.org:6667/webanimations">#webanimations</a> on W3C's IRC

Repository: w3c/csswg-drafts

Ignored Terms: double, boolean, unsigned long, unrestricted double, (unrestricted double or DOMString)

Ignored Vars: did seek, synchronously notify, auto-rewind

Markup Shorthands: markdown yes

Include Mdn Panels: no

WPT Path Prefix: web-animations

WPT Display: open

</pre>

<pre class=anchors>

urlPrefix: https://webidl.spec.whatwg.org/#dfn-; type: dfn; spec: webidl

text: nullable; url: nullable-type

text: convert ecmascript to idl value

urlPrefix: https://webidl.spec.whatwg.org/; type: dfn; spec: webidl

text: a new promise

text: create a new resolved Promise; url: a-promise-resolved-with

text: [EnforceRange]; url: EnforceRange

text: es to dictionary

text: es to DOMString; url: es-to-DOMString

text: DOMString to es; url: DOMString-to-es

text: reject a promise; url: reject

text: resolve a promise; url: resolve

urlPrefix: http://www.ecma-international.org/ecma-262/6.0/#sec-; type: dfn; spec: ecma-262

text: code realms

text: completion record specification type

text: execution contexts

text: EnumerableOwnNames

text: GetIterator

text: GetMethod

text: IteratorStep

text: IteratorValue

text: Promise object; url: promise-objects

text: Promise; url: promise-objects

text: Type; url: ecmascript-data-types-and-values

text: well known symbols

text: [[DefineOwnProperty]]; url: ordinary-object-internal-methods-and-internal-slots-defineownproperty-p-desc

text: [[Get]]; url: ordinary-object-internal-methods-and-internal-slots-get-p-receiver

urlPrefix: https://html.spec.whatwg.org/multipage/browsers.html; type: dfn; spec: html

text: active document

text: being rendered

text: document associated with a window; url: concept-document-window

text: an entry with persisted user state

text: session history entry

urlPrefix: https://html.spec.whatwg.org/multipage/webappapis.html; type: dfn; spec: html

text: current global object

text: document.open(); url: dom-document-open

text: DOM manipulation task source

text: event loop processing model

text: queue a task

text: queue a microtask

text: relevant Realm; url: concept-relevant-realm

text: update the rendering

urlPrefix: https://html.spec.whatwg.org/multipage/webappapis.html; type: interface; spec: html

text: EventHandler

urlPrefix: https://html.spec.whatwg.org/multipage/imagebitmap-and-animations.html.html; type: dfn; spec: html

text: animation frame callbacks; url: animation-frames

text: run the animation frame callbacks

urlPrefix: https://html.spec.whatwg.org/multipage/embedded-content.html; type: dfn; spec: html

text: media element

urlPrefix: https://dom.spec.whatwg.org/; type: dfn; spec: dom

text: create an event; url: concept-event-create

text: dispatch; url: concept-event-dispatch

text: constructing events

text: node document; url: concept-node-document

url: https://html.spec.whatwg.org/#document; type: interface; text: Document; spec: html

url: https://svgwg.org/svg2-draft/pservers.html#StopElementOffsetAttribute; type: element-attr; for: stop; text: offset; spec: svg2

url: https://svgwg.org/svg2-draft/mimereg.html#mime-registration; type: dfn; text: SVG MIME type; spec: svg2

urlPrefix: https://drafts.csswg.org/cssom/; type: dfn; spec: cssom

text: CSS property to IDL attribute

text: IDL attribute to CSS property

text: serialize a CSS value

urlPrefix: https://drafts.csswg.org/css-transitions/; type: dfn; spec: css-transitions-1

text: events from CSS transitions; url: transition-events

text: transitionend

urlPrefix: https://drafts.csswg.org/css-transitions-2/; type: dfn; spec: css-transitions-2

text: owning element (transition); url: owning-element

urlPrefix: https://drafts.csswg.org/css-animations/; type: dfn; spec: css-animations-1

text: events from CSS animations; url: events

urlPrefix: https://drafts.csswg.org/css-animations-2/; type: dfn; spec: css-animations-2

text: owning element (animation); url: owning-element

urlPrefix: https://drafts.csswg.org/css-writing-modes-4/; type: dfn; spec: css-writing-modes-4

text: equivalent physical property; url: logical-to-physical

urlPrefix: https://drafts.csswg.org/css-style-attr/; type: dfn; spec: css-style-attr

text: style attribute

urlPrefix: https://drafts.csswg.org/web-animations-2/; type: dfn; spec: web-animations-2

text: iteration composite operation

text: iteration composite operation accumulate

urlPrefix: https://drafts.css-houdini.org/css-properties-values-api-1/; type: dfn; spec: css-properties-values-api-1

text: syntax definition

text: universal syntax definition

</pre>

<pre class="link-defaults">

spec:cssom-1; type: dfn;

text: CSS declaration block

spec:css-backgrounds-3; type:property;

text:background-image

text:border-width

text:border-bottom-width

text:border-left-width

text:border-right-width

text:border-top-width

text:border-top-color

text:border-top

text:border-color

text:box-shadow

spec:css-cascade-5; type:dfn;

text:computed value

text:shorthand property

spec:css-color-4; type:value; text:transparent

spec:css-display-4; type:property;

text:visibility

text:display

spec:css-fonts-4; type:property;

text:font-size

text:font-weight

spec:css-transforms-1; type:property; text:transform

spec:css-values-4; type:dfn; text:interpolation

spec:dom; type:interface; text:DocumentOrShadowRoot

spec:dom; type:interface; text:EventTarget

spec:dom; type:interface; text:Event

spec:dom; type:dfn; text:descendant

spec:dom; type:dfn; for:/; text:document

spec:dom; type:dfn; for:/; text:shadow root

spec:infra; type:dfn; text:list

spec:infra; type:dfn; for:list; text:extend

</pre>

<script type="text/x-mathjax-config">

MathJax.Hub.Config({showMathMenu: false});

</script>

<script src="https://www.w3.org/scripts/MathJax/2/MathJax.js?config=MML_SVG"></script>

Introduction {#introduction}

============

<div class=informative-bg>

<em>This section is non-normative</em>

This specification defines a model

(the <dfn export>Web Animations model</dfn>)

for supporting animation and synchronization on the Web platform.

It is intended that other specifications will build on this model

and expose its features through declarative means.

In addition, this specification also defines

a programming interface to the model

(the <dfn export>Web Animations <abbr title="Application Programming Interface">API</abbr></dfn>,

defined in [[#programming-interface]])

that may be implemented by user agents that provide support for scripting.

Use cases {#use-cases}

---------

The [=Web Animations model=] is intended to provide the features necessary

for expressing CSS Transitions [[CSS-TRANSITIONS-1]],

CSS Animations [[CSS-ANIMATIONS-1]], and

SVG [[SVG11]].

As such, the use cases of the [=Web Animations model=] are

the union of use cases for those three specifications.

The use cases for the [=Web Animations API=] include the following:

: Inspecting running animations

::

Often Web applications need to wait for certain animated effects to complete

before updating some state.

The [=Web Animations API=] allows such applications

to wait for all currently running animation to complete,

regardless of whether they are defined

by CSS Transitions, CSS Animations, SVG animations,

or created directly using the [=Web Animations API=].

<div class=example>

<pre highlight=javascript>

// Wait until all animations have finished before removing the element

Promise.all(

elem.getAnimations().map(animation => animation.finished)

).then(() => elem.remove());

</pre>

</div>

Alternatively, applications can query the playback state of animations

without waiting.

<div class=example>

<pre highlight=javascript>

const isAnimating = elem.getAnimations().some(

animation => animation.playState === 'running'

);

</pre>

</div>

: Controlling running animations

::

It is sometimes useful to perform [=playback control=] on animations

so that they can respond to external inputs.

For example, it might be necessary to pause all existing animations

before displaying a modal dialog

so that they do not distract the user's attention.

<div class=example>

<pre highlight=javascript>

// Pause all existing animations in the document

for (const animation of document.getAnimations()) {

animation.pause()

}

</pre>

</div>

: Creating animations from script

::

While it is possible to use ECMAScript to perform animation using

<code>requestAnimationFrame</code> [[!HTML]],

such animations behave differently to declarative animation

in terms of how they are represented in the CSS cascade

and the performance optimizations that are possible,

such as performing the animation on a separate thread.

Using the [=Web Animations API=],

it is possible to create animations from script

that have the same behavior and performance characteristics

as declarative animations.

<div class=example>

<pre highlight=javascript>

// Fade out quickly

elem.animate({ transform: 'scale(0)', opacity: 0 }, 300);

</pre>

</div>

: Animation debugging

::

In a complex application, it can be difficult

to determine how an element arrived in its present state.

The [=Web Animations API=] can be used

to inspect running animations to answer questions such as,

“Why is the opacity of this element changing?”

<div class=example>

<pre highlight=javascript>

// Print the id of any opacity animations on elem

for (const animation of elem.getAnimations()) {

if (

animation.effect instanceof KeyframeEffect &&

animation.effect

.getKeyframes()

.some(frame =&gt; frame.hasOwnProperty('opacity'))

) {

console.log(animation.id);

}

}

</pre>

</div>

Likewise, in order to fine tune animations, it is often necessary

to reduce their playback rate and replay them.

<div class=example>

<pre highlight=javascript>

// Slow down and replay any transform animations

const transformAnimations = elem.getAnimations().filter(

animation =&gt;

animation.effect instanceof KeyframeEffect &&

animation.effect.getKeyframes().some(

frame =&gt; frame.hasOwnProperty('transform')

)

);

for (const animation of transformAnimations) {

animation.currentTime = 0;

animation.updatePlaybackRate(0.5);

}

</pre>

</div>

: Testing animations

::

In order to test applications that make use of animations it is often

impractical to wait for such animations to run to completion.

Rather, it is desirable to seek the animations to specific times.

<div class=example>

<pre highlight=javascript>

// Seek to the half-way point of an animation and check that the opacity is 50%

for (const animation of elem.getAnimations()) {

const { delay, activeDuration } = animation.effect.getComputedTiming();

animation.currentTime = delay + activeDuration / 2;

}

assert.strictEqual(getComputedStyle(elem).opacity, '0.5');

// Check that the loading screen is hidden after the animations finish

for (const animation of elem.getAnimations()) {

animation.finish();

}

// Wait one frame so that event handlers have a chance to run

requestAnimationFrame(() =&gt; {

assert.strictEqual(

getComputedStyle(document.querySelector('#loading')).display, 'none');

});

</pre>

</div>

Relationship to other specifications {#relationship-to-other-specifications}

------------------------------------

CSS Transitions [[CSS-TRANSITIONS-1]],

CSS Animations [[CSS-ANIMATIONS-1]],

and SVG [[SVG11]]

all provide mechanisms that generate animated content on a Web page.

Although the three specifications provide many similar features,

they are described in different terms.

This specification proposes an abstract animation model

that encompasses the common features of all three specifications.

This [=Web Animations model=] is backwards-compatible

with the current behavior of these specifications

such that they can be defined in terms of this model without any observable change.

The animation features in SVG 1.1 are defined

in terms of SMIL Animation [[SMIL-ANIMATION]].

It is intended that by defining SVG's animation features

in terms of the [=Web Animations model=],

the dependency between SVG and SMIL Animation can be removed.

As with [=animation frame callbacks=]

(commonly referred to as "requestAnimationFrame") [[HTML]],

the [=Web Animations API=]

allows animations to be created from script.

The animations created using the [=Web Animations API=], however,

once created, are executed entirely by the user agent,

meaning they share the same performance characteristics

as animations defined declaratively.

Using this interface it is possible to create animations

from script in a simpler and more performant manner.

The time values used within the [=Web Animations API=]

correspond with those used in [=animation frame callbacks=] [[HTML]]

and their execution order is defined

such that the two interfaces can be used simultaneously without conflict.

The [=Web Animations API=] component of this specification

makes some additions to interfaces defined in HTML [[!HTML]].

Overview of this specification {#overview-of-this-specification}

------------------------------

This specification begins by defining an abstract model for animation,

the [=Web Animations model=].

This is followed by a programming interface, [=Web Animations API=],

defined in terms of the abstract model.

The programming interface is only relevant

to user agents that provide scripting support.

</div>

Specification conventions {#spec-conventions}

=========================

This specification begins by describing abstract concepts--

such as [=animations=] and [=animation effects=]--

and properties that belong to them,

such as their [=playback rate=] or [=iteration duration=].

In addition to these properties,

there are often specific procedures for updating these properties,

such as the procedure to [=set the playback rate=]

or the procedure to [=set the start time=] of an animation.

Where this specification does not specifically link to a procedure,

text that requires the user agent to update a property,

such as “make |animation|'s [=start time=] [=unresolved=]”,

should be understood to refer to updating the property directly

<em>without</em> invoking any related procedure.

Further conventions not specific to this specification

are described in [[#w3c-conventions]].

Web Animations model overview {#web-animations-model-overview}

=============================

At a glance, the [=Web Animations model=] consists

of two largely independent pieces:

a [=timing model=] and an [=animation model=].

The roles of these pieces are as follows:

: <dfn id="timing-model-dfn">timing model</dfn>

::

Takes a moment in time and converts it to a proportional distance

within a single iteration of an animation,

called the [=iteration progress=].

The current [=iteration index=] is also recorded

since some animations vary each time they repeat.

The [=Web Animations timing model=] is defined in [[#timing-model]].

: <dfn id="animation-model-dfn">animation model</dfn>.

::

Takes the [=iteration progress=] and [=iteration index=] values

produced by the [=timing model=]

and converts them into a series of corresponding values

to apply to the [=target properties=].

The [=Web Animations animation model=] is defined in [[#animation-model]].

<div class=informative-bg>

<em>This section is non-normative</em>

Graphically, this flow can be represented as follows:

<figure>

<img src="images/timing-and-animation-models.svg" width="600"

alt="Overview of the operation of the Web Animations model.">

<figcaption>

Overview of the operation of the [=Web Animations model=].<br>

The current time is input to the [=timing model=]

which produces an [=iteration progress=] value and an [=iteration index=].<br>

These parameters are used as input to the [=animation model=]

which produces the [=target property=] values to apply.

</figcaption>

</figure>

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 describe the [=timing model=]:

at a time of 6 seconds, it calculates 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|timing model]]

and then proceeds to the [[#animation-model|animation model]].

</div>

<!--

████████ ████ ██ ██ ████ ██ ██ ██████

██ ██ ███ ███ ██ ███ ██ ██ ██

██ ██ ████ ████ ██ ████ ██ ██

██ ██ ██ ███ ██ ██ ██ ██ ██ ██ ████

██ ██ ██ ██ ██ ██ ████ ██ ██

██ ██ ██ ██ ██ ██ ███ ██ ██

██ ████ ██ ██ ████ ██ ██ ██████

-->

Timing model {#timing-model}

============

This section describes and defines the behavior

of the <dfn>Web Animations [=timing model=]</dfn>.

Timing in the [=Web Animations model=] is represented through

a hierarchy of relationships between <dfn>timing nodes</dfn>,

in which parent nodes provide timing information to their child nodes

in the form of [=time values=],

ultimately resulting in an [=iteration progress=] and [=iteration index=]

supplied to the [=animations model=]

Timing model characteristics {#timing-model-overview}

----------------------------

<div class=informative-bg>

<em>This section is non-normative</em>

Two features characterize the Web Animations timing model:

it is <em>stateless</em> and it is <em>hierarchical</em>.

### Stateless ### {#stateless}

The Web Animations [=timing model=] operates

by taking an input [=time value=]

and producing an output [=iteration progress=].

Since the output is based solely on the input time

and is independent of previous inputs,

the model can be described as stateless.

This gives the model the following properties:

: Frame-rate independent

::

Since the output is independent of previous inputs,

the rate at which the model is updated

will not affect its progress.

Provided the input times

are proportional to the progress of real-world time,

animations will progress at an identical rate

regardless of the capabilities of the device running them.

: Direction-agnostic

::

Since the sequence of inputs is insignificant,

the model is directionless.

This means that the model can be updated to an arbitrary moment

without requiring any specialized handling.

: Constant-time seeking

::

Since each input is independent of the previous input,

the processing required to perform a seek operation,

even far into the future,

is at least potentially constant.

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

Firstly, a number of methods defined in

the [[#programming-interface|programming interface]] to the model

provide play control such as pausing an animation.

These methods are defined in terms of the time at which they are called

and are therefore stative.

These methods are provided primarily for convenience

and are not part of the core timing model,

but are layered on top.

Similarly, the

[[#reaching-the-end|finishing behavior]] of animations

means that dynamic changes to

the end time of the media ([=associated effect=]) of an animation

can produce a different result

depending on when the change occurs.

This behavior is somewhat unfortunate

but has been deemed intuitive and consistent with HTML.

As a result, the model can only truly be described as stateless

<em>in the absence of dynamic changes to its timing properties</em>.

Finally, each time the model is updated,

it can be considered to establish a temporary state.

While this temporary state affects the values returned

from the [[#programming-interface|programming interface]],

it has no influence on the subsequent updates

and hence does not conflict with the stateless qualities described above.

### Hierarchical ### {#hierarchical}

The other characteristic feature of the timing model

is that time is inherited.

Time begins at a timeline

and cascades down a number of steps to each animation effect.

At each step, time can be shifted backwards or forwards,

scaled, reversed, paused, and repeated.

<figure>

<img src="images/time-hierarchy.svg" width="350"

alt="A hierarchy of timing nodes">

<figcaption>

A hierarchy of timing nodes.

Each node in the tree derives its time from its parent node.

</figcaption>

</figure>

In this level of the specification the hierarchy is shallow.

A subsequent level of this specification

will introduce the concept of group effects

which allows for deeper timing hierarchies.

</div>

Time values {#time-value-section}

-----------

A <dfn>time value</dfn> in the [=Web Animations model=]

is a value that serves the purpose of synchronization.

[=Time values=] are real numbers that nominally represent

a number of milliseconds from some moment.

However, the connection between [=time values=] and wall-clock milliseconds

can be obscured by any number of transformations applied to the value

as it passes through the time hierarchy.

Note: In the future there could be timelines

that are based on scroll position or UI gestures

in which case the connection between time values and milliseconds

will be weakened even further.

A [=time value=] can be <dfn>unresolved</dfn>,

i.e. represent the absence of a meaningful [=time value=].

This can happen if

a [=timing node=] is not in a state to produce a [=time value=].

Timelines {#timelines}

---------

A <dfn export>timeline</dfn> is a [=timing node=]

that provides a source of [=time values=].

At any given moment, a [=timeline=] has a single current [=time value=]

known simply as the timeline's <dfn export for=timeline>current time</dfn>.

Changes in a [=timeline=]’s [=timeline/current time=]

are ultimately what drive [=animations=] in the [=Web Animations model=].

A [=timeline=] might not always be able to return a meaningful [=time value=],

but only an [=unresolved=] time value.

For example, its [=timeline/current time=] might be defined relative to

a moment that has yet to occur,

such as the firing of a document's load event.

A [=timeline=] is considered to be

<dfn export lt="inactive timeline">inactive</dfn>

when its [=time value=] is [=unresolved=],

and <dfn export lt="active timeline">active</dfn> otherwise.

A [=timeline=] is

<dfn export lt="monotonically increasing timeline" local-lt="monotonically increasing">monotonically increasing</dfn>

if its reported [=timeline/current time=] is always greater than or equal to

its previously reported [=timeline/current time=].

Specific types of [=timelines=] may define a procedure to

<dfn lt="timeline time to origin-relative time" export>convert

a timeline time to an origin-relative time</dfn>

for [=time value=] <var ignore>time</var>,

so that the [=time values=] produced by wallclock-based timelines

can be compared.

A [=timeline=] can be

<dfn lt="timeline associated with a document">associated with a document</dfn>.

### Document timelines ### {#document-timelines}

A <dfn export>document timeline</dfn> is a type of [=timeline=]

that is [=timeline associated with a document|associated with a document=]

and whose [=timeline/current time=] is calculated

as a fixed offset from the |now| timestamp provided

each time the [=update animations and send events=] procedure is run.

This fixed offset is equal to

the [=timeline/current time=] of the [=default document timeline=]

when this timeline’s [=timeline/current time=] was zero,

and is thus referred to as

the document timeline's <dfn>origin time</dfn>.

Issue(2079): There must be a better term than "origin time"&mdash;

it's too similar to "time origin".

Prior to establishing the [=time origin=] for its associated document,

a [=document timeline=] is [=inactive timeline|inactive=].

After a [=document timeline=] becomes [=active timeline|active=],

it is [=monotonically increasing=].

A [=document timeline=] that is associated

with a {{Document}} that is not an [=active document=]

is also considered to be [=inactive timeline|inactive=].

To <a lt="timeline time to origin-relative time">convert

a timeline time, |timeline time|, to an origin-relative time</a>

for a document timeline, |timeline|,

return the sum of the |timeline time| and |timeline|'s [=origin time=].

If |timeline| is inactive, return an [=unresolved=] [=time value=].

#### The default document timeline #### {#the-documents-default-timeline}

Each {{Document}} has a [=document timeline=] called the

<dfn export for="document">default document timeline</dfn>.

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.

#### Relationship to wall-clock time #### {#document-wallclock-time}

<div class=informative-bg>

<em>This section is non-normative</em>

Since no scaling is applied to

the |now| timestamp values provided to a [=document timeline=],

the [=time values=] it produces will be

proportional to wall-clock milliseconds.

Furthermore, since the [=time values=]

of the [=default document timeline=]

have a zero offset from the [=time origin=],

<code>document.timeline.currentTime</code> will roughly correspond

to <a href="https://www.w3.org/TR/hr-time/#dom-performance-now"><code>Performance.now()</code></a> [[HR-TIME]]

with the exception that <code>document.timeline.currentTime</code>

does not change in between calls

to the [=update animations and send events=] procedure.

</div>

Animation Frames {#animation-frame-loop}

----------------

<div algorithm>

When asked to <dfn export>update animations and send events</dfn>

for a {{Document}} |doc| at timestamp |now|,

run these steps:

1. Update the [=timeline/current time=] of all timelines

<a lt="timeline associated with a document">associated with |doc|</a>

passing |now| as the timestamp.

<div class=note>

Due to the hierarchical nature of the timing model,

updating the [=timeline/current time=] of a [=timeline=] also involves:

* Updating the [=animation/current time=] of any [=animations=]

[=associated with a timeline|associated with=] the timeline.

* Running the [=update an animation's finished state=] procedure

for any animations whose [=animation/current time=] has been updated.

* Queueing [=animation events=] for any such animations.

</div>

1. [=Remove replaced animations=] for |doc|.

1. [=Perform a microtask checkpoint=].

Note: This is to ensure that any microtasks queued up

as a result of resolving or rejecting Promise objects

as part of updating timelines in the previous step,

run their callbacks prior to dispatching animation events.

1. Let |events to dispatch| be a copy of |doc|'s [=pending animation event queue=].

1. Clear |doc|'s [=pending animation event queue=].

1. Perform a stable sort of the [=animation events=] in |events to dispatch|

as follows:

1. Sort the events by their [=scheduled event time=]

such that events that were scheduled to occur earlier

sort before events scheduled to occur later,

and events whose scheduled event time is [=unresolved=]

sort before events with a [=resolved=]

scheduled event time.

1. Within events with equal [=scheduled event times=],

sort by their [=composite order=].

Note: The purpose of sorting events is to ensure that, as best possible,

even on devices with differing capabilities

and hence different frame rates,

events are dispatched in a consistent order.

Note: The requirement for the sort to be a stable sort

is because sometimes multiple events can be queued

with the same scheduled event time.

For example, a CSS animation with a duration of zero would dispatch

both an <code>animationstart</code> and an <code>animationend</code> event

with the same scheuled event time,

and the order of these events should be preserved.

1. [=Dispatch=] each of the events in |events to dispatch| at their

corresponding target using the order established in the previous step.

</div>

It is often convenient to describe each time this procedure is invoked

as establishing a new <dfn export>animation frame</dfn>.

Changes to the timing properties of [=animations=] or [=animation effects=],

or the addition and removal of the objects can

cause the output of the timing or animation model to change,

but these operations in themselves do not create a new [=animation frame=];

rather they merely update the current [=animation frame=].

Animations {#animations}

----------

An <dfn export id="concept-animation">animation</dfn>

is a [=timing node=] that

binds an [=animation effect=] child,

called its <dfn export for=animation>associated effect</dfn>,

to a [=timeline=] parent so that it runs.

Both of these associations are optional and configurable

such that an [=animation=] can have

no [=associated effect=] or [=timeline=] at a given moment.

[=Animations=] also allow run-time control of the connection

between the [=animation effect=] and its [=timeline=],

through <dfn>playback control</dfn> functions such as

[[#pausing-an-animation-section|pausing]],

[[#setting-the-current-time-of-an-animation|seeking]],

and [[#speed-control|speed control]].

[=Time values=] flow from the [=timeline=] through the [=animation=]

to the [=associated effect=].

The [=time value=] provided to an [=animation=]’s [=associated effect=]

is called the [=animation=]’s <dfn export for=animation>current time</dfn>.

Note: The relationship between an animation and an [=animation effect=]

is analogous to that of a DVD player and a DVD.

In addition to its [=timeline=], [=associated effect=],

and [=animation/current time=]

an [=animation=] has the following:

<dl export dfn-for="animation">

: <dfn>document for timing</dfn>

::

The {{Document}} with which the [=animation=]’s [=timeline=] is

[=timeline associated with a document|associated=].

If an animation is not associated with a timeline,

or its timeline is not associated with a document,

then it has no [=document for timing=].

: <dfn>start time</dfn>

::

The [=time value=] of its [=timeline=]

when its [=associated effect=] is scheduled to begin playback.

An animation's start time is initially [=unresolved=].

: <dfn>hold time</dfn>

::

A [=time value=],

which is used to freeze the animation's [=animation/current time=] output

in circumstances such as pausing.

The [=hold time=] is initially [=unresolved=].

</dl>

In order to establish the relative ordering of conflicting [=animations=],

animations are appended to a <dfn export>global animation list</dfn>

in the order in which they are created.

Certain [=animation class|classes of animations=], however,

may provide alternative means of ordering animations

(see [[#animation-classes]]).

### Calculating the current time of an animation ### {#the-current-time-of-an-animation}

The [=animation/current time=] of an [=animation=] is calculated from

the first matching condition below:

<dl class=switch>

: If the animation's [=hold time=] is [=unresolved|resolved=],

::

The [=animation/current time=] is the animation's [=hold time=].

: If <em>any</em> of the following are true:

* the animation has no associated [=timeline=], or

* the associated [=timeline=] is [=inactive timeline|inactive=], or

* the animation's [=start time=] is [=unresolved=],

::

The [=animation/current time=] is an [=unresolved=] time value.

: Otherwise,

::

<blockquote>

<code><a for="animation">current time</a> =

(<var>timeline time</var> − <a>start time</a>)

× <a>playback rate</a></code>

</blockquote>

Where |timeline time| is the current [=time value=]

of the associated [=timeline=].

The [=playback rate=] value is defined in [[#speed-control]].

</dl>

### Setting the timeline of an animation ### {#setting-the-timeline}

<div algorithm>

The procedure to

<dfn export for=animation>set the timeline of an animation</dfn>,

|animation|,

to |new timeline| which may be null,

is as follows:

1. Let |old timeline| be

the current [=timeline=] of |animation|, if any.

1. If |new timeline| is the same object as |old timeline|,

abort this procedure.

1. Let the [=timeline=] of |animation| be

|new timeline|.

1. If the [=start time=] of |animation| is [=unresolved|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 [=animation/current time=].

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

</div>

<h4 id="setting-the-associated-effect" oldids="setting-the-target-effect">

Setting the associated effect of an animation</h4>

<div algorithm>

The procedure to <dfn export for=animation>set the associated effect of an animation</dfn>,

|animation|,

to |new effect| which may be null, is as follows:

1. Let |old effect| be

the current [=associated effect=] of |animation|, if any.

1. If |new effect| is the same object as |old effect|,

abort this procedure.

1. If |animation| has a [=pending pause task=],

reschedule that task to run as soon as |animation| is [=ready=].

1. If |animation| has a [=pending play task=],

reschedule that task to run as soon as

|animation| is [=ready=] to play |new effect|.

1. If |new effect| is not <code>null</code>

and if |new effect| is the [=associated effect=]

of another [=animation=], |previous animation|,

run the procedure to [=set the associated effect of an animation=]

(this procedure)

on |previous animation|,

passing null as |new effect|.

1. Let the [=associated effect=] of |animation| be

|new effect|.

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