Web Animations Module Level 1

Web Animations Module Level 1
Web Animations Module Level 1
Editor’s Draft
24 November 2025
More details about this document
This version:
Latest published version:
Previous Versions:
Version History:
Feedback:
CSSWG Issues Repository
Inline In Spec
Editors:
Brian Birtles
Invited Expert
Robert Flack
Google
Stephen McGruer
Google
Antoine Quint
Apple Inc
Former Editors:
Shane Stephens
Google
Douglas Stockwell
Google
Alex Danilo
Google
Tab Atkins
Google
Suggest an Edit for this Spec:
GitHub Editor
Participate:
Fix the text through GitHub
Join the "waapi" channel on the
Animation at Work
slack
IRC:
#webanimations
on W3C’s IRC
Test Suite:
World Wide Web Consortium
W3C
liability
trademark
and
permissive document license
rules apply.
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.
CSS
is a language for describing the rendering of structured documents
(such as HTML and XML)
on screen, on paper, etc.
Status of this document
This is a public copy of the editors’ draft.
It is provided for discussion only and may change at any moment.
Its publication here does not imply endorsement of its contents by W3C.
Don’t cite this document other than as work in progress.
Please send feedback
by
filing issues in GitHub
(preferred),
including the spec code “web-animations” in the title, like this:
“[web-animations]
…summary of comment…
”.
All issues and comments are
archived
Alternately, feedback can be sent to the (
archived
) public mailing list
www-style@w3.org
This document is governed by the
18 August 2025 W3C Process Document
1.
Introduction
This section is non-normative
This specification defines a model
(the
Web Animations model
for supporting animation and synchronization on the Web platform.
It is intended that other specifications will build on this model
and expose its features through declarative means.
In addition, this specification also defines
a programming interface to the model
(the
Web Animations
API
defined in
§ 6 Programming interface
that may be implemented by user agents that provide support for scripting.
1.1.
Use cases
The
Web Animations model
is intended to provide the features necessary
for expressing CSS Transitions
[CSS-TRANSITIONS-1]
CSS Animations
[CSS-ANIMATIONS-1]
, and
SVG
[SVG11]
As such, the use cases of 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
// Wait until all animations have finished before removing the element
Promise
all
elem
getAnimations
().
map
animation
=>
animation
finished
).
then
(()
=>
elem
remove
());
Alternatively, applications can query the playback state of animations
without waiting.
const
isAnimating
elem
getAnimations
().
some
animation
=>
animation
playState
===
'running'
);
Controlling running animations
It is sometimes useful to perform
playback control
on animations
so that they can respond to external inputs.
For example, it might be necessary to pause all existing animations
before displaying a modal dialog
so that they do not distract the user’s attention.
// Pause all existing animations in the document
for
const
animation
of
document
getAnimations
())
animation
pause
()
Creating animations from script
While it is possible to use ECMAScript to perform animation using
requestAnimationFrame
[HTML]
such animations behave differently to declarative animation
in terms of how they are represented in the CSS cascade
and the performance optimizations that are possible,
such as performing the animation on a separate thread.
Using the
Web Animations API
it is possible to create animations from script
that have the same behavior and performance characteristics
as declarative animations.
// Fade out quickly
elem
animate
({
transform
'scale(0)'
opacity
},
300
);
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?”
// Print the id of any opacity animations on elem
for
const
animation
of
elem
getAnimations
())
if
animation
effect
instanceof
KeyframeEffect
&&
animation
effect
getKeyframes
()
some
frame
=>
frame
hasOwnProperty
'opacity'
))
console
log
animation
id
);
Likewise, in order to fine tune animations, it is often necessary
to reduce their playback rate and replay them.
// Slow down and replay any transform animations
const
transformAnimations
elem
getAnimations
().
filter
animation
=>
animation
effect
instanceof
KeyframeEffect
&&
animation
effect
getKeyframes
().
some
frame
=>
frame
hasOwnProperty
'transform'
);
for
const
animation
of
transformAnimations
animation
currentTime
animation
updatePlaybackRate
0.5
);
Testing animations
In order to test applications that make use of animations it is often
impractical to wait for such animations to run to completion.
Rather, it is desirable to seek the animations to specific times.
// Seek to the half-way point of an animation and check that the opacity is 50%
for
const
animation
of
elem
getAnimations
())
const
delay
activeDuration
animation
effect
getComputedTiming
();
animation
currentTime
delay
activeDuration
assert
strictEqual
getComputedStyle
elem
).
opacity
'0.5'
);
// Check that the loading screen is hidden after the animations finish
for
const
animation
of
elem
getAnimations
())
animation
finish
();
// Wait one frame so that event handlers have a chance to run
requestAnimationFrame
(()
=>
assert
strictEqual
getComputedStyle
document
querySelector
'#loading'
)).
display
'none'
);
});
1.2.
Relationship to other specifications
CSS Transitions
[CSS-TRANSITIONS-1]
CSS Animations
[CSS-ANIMATIONS-1]
and SVG
[SVG11]
all provide mechanisms that generate animated content on a Web page.
Although the three specifications provide many similar features,
they are described in different terms.
This specification proposes an abstract animation model
that encompasses the common features of all three specifications.
This
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]
1.3.
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.
2.
Specification conventions
This specification begins by describing abstract concepts—​such as
animations
and
animation effects
—​and properties that belong to them,
such as their
playback rate
or
iteration duration
In addition to these properties,
there are often specific procedures for updating these properties,
such as the procedure to
set the playback rate
or the procedure to
set the start time
of an animation.
Where this specification does not specifically link to a procedure,
text that requires the user agent to update a property,
such as “make
animation
’s
start time
unresolved
”,
should be understood to refer to updating the property directly
without
invoking any related procedure.
Further conventions not specific to this specification
are described in
Document conventions
3.
Web Animations model overview
At a glance, the
Web Animations model
consists
of two largely independent pieces:
timing model
and an
animation model
The roles of these pieces are as follows:
timing model
Takes a moment in time and converts it to a proportional distance
within a single iteration of an animation,
called the
iteration progress
The current
iteration index
is also recorded
since some animations vary each time they repeat.
The
Web Animations timing model
is defined in
§ 4 Timing model
animation model
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
§ 5 Animation model
This section is non-normative
Graphically, this flow can be represented as follows:
Overview of the operation of the
Web Animations model
The current time is input to the
timing model
which produces an
iteration progress
value and an
iteration index
These parameters are used as input to the
animation model
which produces the
target property
values to apply.
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
and then proceeds to the
animation model
4.
Timing model
This section describes and defines the behavior
of the
Web Animations
timing model
Timing in the
Web Animations model
is represented through
a hierarchy of relationships between
timing nodes
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
4.1.
Timing model characteristics
This section is non-normative
Two features characterize the Web Animations timing model:
it is
stateless
and it is
hierarchical
4.1.1.
Stateless
The Web Animations
timing model
operates
by taking an input
time 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
to the model
provide play control such as pausing an animation.
These methods are defined in terms of the time at which they are called
and are therefore stative.
These methods are provided primarily for convenience
and are not part of the core timing model,
but are layered on top.
Similarly, the
finishing behavior
of animations
means that dynamic changes to
the end time of the media (
associated effect
) of an animation
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
in the absence of dynamic changes to its timing properties
Finally, each time the model is updated,
it can be considered to establish a temporary state.
While this temporary state affects the values returned
from the
programming interface
it has no influence on the subsequent updates
and hence does not conflict with the stateless qualities described above.
4.1.2.
Hierarchical
The other characteristic feature of the timing model
is that time is inherited.
Time begins at a timeline
and cascades down a number of steps to each animation effect.
At each step, time can be shifted backwards or forwards,
scaled, reversed, paused, and repeated.
A hierarchy of timing nodes.
Each node in the tree derives its time from its parent node.
In this level of the specification the hierarchy is shallow.
A subsequent level of this specification
will introduce the concept of group effects
which allows for deeper timing hierarchies.
4.2.
Time values
time value
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.
time value
can be
unresolved
i.e. represent the absence of a meaningful
time value
This can happen if
timing node
is not in a state to produce a
time value
4.3.
Timelines
timeline
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
current time
Changes in a
timeline
’s
current time
are ultimately what drive
animations
in the
Web Animations model
timeline
might not always be able to return a meaningful
time value
but only an
unresolved
time value.
For example, its
current time
might be defined relative to
a moment that has yet to occur,
such as the firing of a document’s load event.
timeline
is considered to be
inactive
when its
time value
is
unresolved
and
active
otherwise.
timeline
is
monotonically increasing
if its reported
current time
is always greater than or equal to
its previously reported
current time
Specific types of
timelines
may define a procedure to
convert
a timeline time to an origin-relative time
for
time value
time
so that the
time values
produced by wallclock-based timelines
can be compared.
timeline
can be
associated with a document
4.3.1.
Document timelines
document timeline
is a type of
timeline
that is
associated with a document
and whose
current time
is calculated
as a fixed offset from the
now
timestamp provided
each time the
update animations and send events
procedure is run.
This fixed offset is equal to
the
current time
of the
default document timeline
when this timeline’s
current time
was zero,
and is thus referred to as
the document timeline’s
origin time
There must be a better term than "origin time"—
it’s too similar to "time origin".
[Issue #2079]
Prior to establishing the
time origin
for its associated document,
document timeline
is
inactive
After a
document timeline
becomes
active
it is
monotonically increasing
document timeline
that is associated
with a
Document
that is not an
active document
is also considered to be
inactive
To
convert
a timeline time,
timeline time
, to an origin-relative time
for a document timeline,
timeline
return the sum of the
timeline time
and
timeline
’s
origin time
If
timeline
is inactive, return an
unresolved
time value
4.3.1.1.
The default document timeline
Each
Document
has a
document timeline
called the
default document timeline
The
default document timeline
is unique to each document
and persists for the lifetime of the document,
including calls to
document.open()
[HTML]
The
default document timeline
has an
origin time
of zero.
4.3.1.2.
Relationship to wall-clock time
This section is non-normative
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
document.timeline.currentTime
will roughly correspond
to
Performance.now()
[HR-TIME]
with the exception that
document.timeline.currentTime
does not change in between calls
to the
update animations and send events
procedure.
4.4.
Animation Frames
When asked to
update animations and send events
for a
Document
doc
at timestamp
now
run these steps:
Update the
current time
of all timelines
associated with
doc
passing
now
as the timestamp.
Due to the hierarchical nature of the timing model,
updating the
current time
of a
timeline
also involves:
Updating the
current time
of any
animations
associated with
the timeline.
Running the
update an animation’s finished state
procedure
for any animations whose
current time
has been updated.
Queueing
animation events
for any such animations.
Remove replaced animations
for
doc
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.
Let
events to dispatch
be a copy of
doc
’s
pending animation event queue
Clear
doc
’s
pending animation event queue
Perform a stable sort of the
animation events
in
events to dispatch
as follows:
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.
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
animationstart
and an
animationend
event
with the same scheuled event time,
and the order of these events should be preserved.
Dispatch
each of the events in
events to dispatch
at their
corresponding target using the order established in the previous step.
It is often convenient to describe each time this procedure is invoked
as establishing a new
animation frame
Changes to the timing properties of
animations
or
animation effects
or the addition and removal of the objects 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
4.5.
Animations
An
animation
is a
timing node
that
binds an
animation effect
child,
called its
associated effect
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
playback control
functions such as
pausing
seeking
and
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
current time
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
current time
an
animation
has the following:
document for timing
The
Document
with which the
animation
’s
timeline
is
associated
If an animation is not associated with a timeline,
or its timeline is not associated with a document,
then it has no
document for timing
start time
The
time value
of its
timeline
when its
associated effect
is scheduled to begin playback.
An animation’s start time is initially
unresolved
hold time
time value
which is used to freeze the animation’s
current time
output
in circumstances such as pausing.
The
hold time
is initially
unresolved
In order to establish the relative ordering of conflicting
animations
animations are appended to a
global animation list
in the order in which they are created.
Certain
classes of animations
, however,
may provide alternative means of ordering animations
(see
§ 5.4.1 Animation classes
).
4.5.1.
Calculating the current time of an animation
The
current time
of an
animation
is calculated from
the first matching condition below:
If the animation’s
hold time
is
resolved
The
current time
is the animation’s
hold time
If
any
of the following are true:
the animation has no associated
timeline
, or
the associated
timeline
is
inactive
, or
the animation’s
start time
is
unresolved
The
current time
is an
unresolved
time value.
Otherwise,
current time
timeline time
start time
playback rate
Where
timeline time
is the current
time value
of the associated
timeline
The
playback rate
value is defined in
§ 4.5.15 Speed control
4.5.2.
Setting the timeline of an animation
The procedure to
set the timeline of an animation
animation
to
new timeline
which may be null,
is as follows:
Let
old timeline
be
the current
timeline
of
animation
, if any.
If
new timeline
is the same object as
old timeline
abort this procedure.
Let the
timeline
of
animation
be
new timeline
If the
start time
of
animation
is
resolved
make
animation
’s
hold time
unresolved
Note:
This step ensures that the
finished play state
of
animation
is not “sticky”,
but is re-evaluated based on its updated
current time
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.3.
Setting the associated effect of an animation
The procedure to
set the associated effect of an animation
animation
to
new effect
which may be null, is as follows:
Let
old effect
be
the current
associated effect
of
animation
, if any.
If
new effect
is the same object as
old effect
abort this procedure.
If
animation
has a
pending pause task
reschedule that task to run as soon as
animation
is
ready
If
animation
has a
pending play task
reschedule that task to run as soon as
animation
is
ready
to play
new effect
If
new effect
is not
null
and if
new effect
is the
associated effect
of another
animation
previous animation
run the procedure to
set the associated effect of an animation
(this procedure)
on
previous animation
passing null as
new effect
Let the
associated effect
of
animation
be
new effect
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.4.
Setting the current time of an animation
The
current time
of an
animation
can be set to a new value
to
seek
the animation.
The procedure for setting the current time is defined in two parts.
The procedure to
silently set the current time
of an animation,
animation
to
seek time
is as follows:
If
seek time
is an
unresolved
time value,
then perform the following steps.
If the
current time
is
resolved
then
throw
TypeError
Abort these steps.
Update either
animation
’s
hold time
or
start time
as follows:
If
any
of the following conditions are true:
animation
’s
hold time
is
resolved
, or
animation
’s
start time
is
unresolved
, or
animation
has no associated
timeline
or the
associated
timeline
is
inactive
, or
animation
’s
playback rate
is 0,
Set
animation
’s
hold time
to
seek time
Otherwise,
Set
animation
’s
start time
to the result of evaluating
timeline time
− (
seek time
playback rate
where
timeline time
is the current
time value
of the
timeline
associated with
animation
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
The procedure to
set the current time
of an animation,
animation
to
seek time
is as follows:
Run the steps to
silently set the current time
of
animation
to
seek time
If
animation
has a
pending pause task
synchronously complete the pause operation
by performing the following steps:
Set
animation
’s
hold time
to
seek time
Apply any pending playback rate
to
animation
Make
animation
’s
start time
unresolved
Cancel the
pending pause task
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.5.
Setting the start time of an animation
The procedure to
set the start time
of an
animation
animation
to
new start time
is as follows:
Let
timeline time
be the current
time value
of the
timeline
that
animation
is associated with.
If there is no
timeline
associated with
animation
or the associated timeline is
inactive
let the
timeline time
be
unresolved
If
timeline time
is
unresolved
and
new start time
is
resolved
make
animation
’s
hold 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
Let
previous current time
be
animation
’s
current time
Note:
This is the
current time
after applying the changes from the previous step,
which can cause the current time to become
unresolved
Apply any pending playback rate
on
animation
Set
animation
’s
start time
to
new start time
Update
animation
’s
hold time
based on
the first matching condition from the following:
If
new start time
is
resolved
If
animation
’s
playback rate
is not zero,
make
animation
’s
hold time
unresolved
Otherwise (
new start time
is
unresolved
),
Set
animation
’s
hold time
to
previous current time
even if
previous current time
is
unresolved
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
This section is non-normative
Some operations performed by an
animation
might not occur instantaneously.
For example, some user agents might delegate the playback of an animation
to a separate process or to specialized graphics hardware,
each of which could incur some setup overhead.
If such an animation is timed
from the moment when the animation was triggered
there can be a significant jump
between the first and second frames of the animation
corresponding to the setup time involved.
To avoid this problem,
Web Animations typically begins timing animations
from the moment when the first frame of the animation is complete.
This is represented by an
unresolved
start time
on the
animation
which becomes resolved when the animation is
ready
Content can opt out of this behavior by setting
the
start time
to a
resolved
time value
An animation is
ready
at the first moment
where
both
of the following conditions are true:
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
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
).
Note that since the same object is used for both
pending play and pending pause requests,
authors are advised to check the state of the animation
when the
Promise object
is resolved.
For example, in the following code fragment,
the state of the animation will be
running
when the
current ready promise
is resolved.
This is because the
play
operation occurs
while a
pending play task
is still queued
and hence the
current ready promise
is re-used.
animation
pause
();
animation
ready
then
function
()
// Displays 'running'
alert
animation
playState
);
});
animation
play
();
4.5.8.
Playing an animation
The procedure to
play an animation
animation
given a flag
auto-rewind
is as follows:
Let
aborted pause
be a boolean flag
that is true if
animation
has a
pending pause task
and false otherwise.
Let
has pending ready promise
be a boolean flag
that is initially false.
Let
seek time
be a
time value
that is initially
unresolved
If the
auto-rewind
flag is true,
perform the steps corresponding to the
first
matching condition
from the following, if any:
If
animation
’s
effective playback rate
≥ 0,
and
animation
’s
current time
is
either
unresolved
, or
less than zero, or
greater than or equal to
associated effect end
Set
seek time
to zero.
If
animation
’s
effective playback rate
< 0,
and
animation
’s
current time
is
either
unresolved
, or
less than or equal to zero, or
greater than
associated effect end
If
associated effect end
is positive infinity,
throw
an "
InvalidStateError
DOMException
and abort these steps.
Otherwise,
Set
seek time
to
animation
’s
associated effect end
If the following three conditions are
all
satisfied:
seek time
is
unresolved
, and
animation
’s
start time
is
unresolved
, and
animation
’s
current time
is
unresolved
set
seek time
to zero.
Note:
The above step ensures that this procedure will play an idle animation
regardless of the setting of the
auto-rewind
flag.
Let
has finite timeline
be true if
animation
has an associated
timeline
that is not
monotonically increasing
If
seek time
is
resolved
If
has finite timeline
is true,
Set
animation
’s
start time
to
seek time
Let
animation
’s
hold time
be
unresolved
Apply any pending playback rate
on
animation
Otherwise,
Set
animation
’s
hold time
to
seek time
If
animation
’s
hold time
is
resolved
let its
start time
be
unresolved
If
animation
has a
pending play task
or a
pending pause task
Cancel that task.
Set
has pending ready promise
to true.
If the following four conditions are
all
satisfied:
animation
’s
hold time
is
unresolved
, and
seek time
is
unresolved
, and
aborted pause
is false, and
animation
does
not
have a
pending playback rate
abort this procedure.
If
has pending ready promise
is false,
let
animation
’s
current ready promise
be
a new promise
in the
relevant Realm
of
animation
Schedule a task to run as soon as
animation
is
ready
The task shall perform the following steps:
Assert that at least one of
animation
’s
start time
or
hold time
is
resolved
Let
ready time
be the
time value
of
the
timeline
associated with
animation
at the moment when
animation
became
ready
Perform the steps corresponding to the first matching condition below,
if any:
If
animation
’s
hold time
is
resolved
Apply any pending playback rate
on
animation
Let
new start time
be the result of evaluating
ready time
hold time
playback rate
for
animation
If the
playback rate
is zero,
let
new start time
be simply
ready time
Set the
start time
of
animation
to
new start time
If
animation
’s
playback rate
is not 0,
make
animation
’s
hold time
unresolved
If
animation
’s
start time
is resolved
and
animation
has a
pending playback rate
Let
current time to match
be the result of evaluating
ready time
start time
playback rate
for
animation
Apply any pending playback rate
on
animation
If
animation
’s
playback rate
is zero,
let
animation
’s
hold time
be
current time to match
Let
new start time
be the result of evaluating
ready time
current time to match
playback rate
for
animation
If the
playback rate
is zero,
let
new start time
be simply
ready time
Set the
start time
of
animation
to
new start time
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.
The above requirement to run the
pending play task
asynchronously
ensures that code such as the following
behaves consistently between implementations:
animation
play
();
animation
ready
then
()
=>
console
log
'Playback commenced'
);
},
()
=>
console
log
'Playback was canceled'
);
);
// Suppose some condition requires playback to be canceled...
animation
cancel
();
// "Playback was canceled" will be printed to the console.
In the above code, were the
pending play task
run synchronously,
the
current ready promise
would not be rejected.
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.
The procedure to
pause an animation
animation
is as follows:
If
animation
has a
pending pause task
abort these steps.
If the
play state
of
animation
is
paused
abort these steps.
Let
seek time
be
time value
that is initially
unresolved
Let
has finite timeline
be true
if
animation
has an associated
timeline
that is not
monotonically increasing
If the
animation
’s
current time
is
unresolved
perform the steps according to the first matching condition below:
If
animation
’s
playback rate
is ≥ 0,
Set
seek time
to zero.
Otherwise,
If
associated effect end
for
animation
is positive infinity,
throw
an "
InvalidStateError
DOMException
and abort these steps.
Otherwise,
Set
seek time
to
animation
’s
associated effect end
If
seek time
is
resolved
If
has finite timeline
is true,
Set
animation
’s
start time
to
seek time
Otherwise,
Set
animation
’s
hold time
to
seek time
Let
has pending ready promise
be a boolean flag
that is initially false.
If
animation
has a
pending play task
cancel that task
and let
has pending ready promise
be true.
If
has pending ready promise
is false,
set
animation
’s
current ready promise
to
a new promise
in the
relevant Realm
of
animation
Schedule a task to be executed at the first possible moment
where
both
of the following conditions are true:
the user agent has performed any processing necessary to suspend
the playback of
animation
’s
associated effect
, if any.
the animation is associated with a
timeline
that is not
inactive
The task shall perform the following steps:
Let
ready time
be the time value of
the timeline associated with
animation
at the moment when the user agent completed processing necessary
to suspend playback of
animation
’s
associated effect
If
animation
’s
start time
is
resolved
and its
hold time
is
not
resolved,
let
animation
’s
hold time
be the result of evaluating
ready time
start time
playback rate
Note:
The
hold time
might be already set
if the animation is
finished
or if the animation has a
pending play task
In either case we want to preserve the
hold time
as we enter the
paused
state.
Apply any pending playback rate
on
animation
Make
animation
’s
start time
unresolved.
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.
So long as the above task is scheduled but has yet to run,
animation
is described as having a
pending pause task
While the task is running, however,
animation
does
not
have a
pending pause task
As with the
pending play task
the user agent must run the
pending pause task
asynchronously,
although that could be as soon as the next
microtask checkpoint
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.10.
Reaching the end
This section is non-normative
DVD players or cassette players typically continue playing
until they reach the end of their media at which point they stop.
If such players are able to play in reverse,
they typically stop playing when they reach the beginning of their media.
In order to emulate this behavior,
and to provide consistency with HTML’s
media elements
[HTML]
the
current time
of Web Animations' animations
do not play forwards beyond the
end time
of their
associated effect
or play backwards past time zero.
An animation that has reached the natural boundary of its playback range
is said to have
finished
Graphically, the effect of limiting the current time is shown below.
The effect of limiting the
current time
of an
animation
with a start time of 1s,
an
associated effect
of length 3s,
and a positive
playback rate
After the current time of the animation reaches
the end of the associated effect,
it is capped at 3s.
It is possible, however, to
seek
the
current time
of an
animation
to a time past the end of the
associated effect
When doing so, the current time will not progress
but the animation will act as if it had been paused
at the seeked time.
This allows, for example,
seeking
the
current time
of an animation
with
no
associated effect
to 5s.
If
associated effect
with an
end time
later than 5s
is later associated with the animation,
playback will begin from the 5s mark.
Similar behavior to the above scenario 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.
The procedure to
update an animation’s finished state
for
animation
given a flag
did seek
(to indicate if the update is being performed
after
setting the current time
),
and a flag
synchronously notify
(to indicate the update was called
in a context where we expect finished event queueing
and finished promise resolution to happen immediately,
if at all)
is as follows:
Let the
unconstrained current time
be
the result of calculating the
current time
substituting an
unresolved
time value for the
hold time
if
did seek
is false.
If
did seek
is true,
the
unconstrained current time
is equal to the
current time
Note:
This is required to accommodate timelines that can change direction.
Without this definition, a once-finished animation would remain finished
even when its timeline progresses in the opposite direction.
If
all three
of the following conditions are true,
the
unconstrained current time
is
resolved
and
animation
’s
start time
is
resolved
and
animation
does
not
have
pending play task
or a
pending pause task
then update
animation
’s
hold time
based on
the first matching condition for
animation
from below, if any:
If
playback rate
> 0
and
unconstrained current time
is
greater than or equal to
associated effect end
If
did seek
is true,
let the
hold time
be the value of
unconstrained current time
If
did seek
is false,
let the
hold time
be the maximum value
of
previous current time
and
associated effect end
If the
previous current time
is
unresolved
let the
hold time
be
associated effect end
If
playback rate
< 0
and
unconstrained current time
is less than or equal to 0,
If
did seek
is true,
let the
hold time
be the value of
unconstrained current time
If
did seek
is false,
let the
hold time
be the minimum value
of
previous current time
and zero.
If the
previous current time
is
unresolved
let the
hold time
be zero.
If
playback rate
≠ 0,
and
animation
is associated with an
active timeline
Perform the following steps:
If
did seek
is true
and the
hold time
is
resolved
let
animation
’s
start time
be equal to
the result of evaluating
timeline time
− (
hold time
playback rate
where
timeline time
is the current
time value
of
the
timeline
associated with
animation
Let the
hold time
be
unresolved
Set the
previous current time
of
animation
to be
the result of calculating its
current time
Let
current finished state
be true
if the
play state
of
animation
is
finished
Otherwise, let it be false.
If
current finished state
is true
and the
current finished promise
is not yet resolved,
perform the following steps:
Let
finish notification steps
refer to
the following procedure:
If
animation
’s
play state
is not equal to
finished
abort these steps.
Resolve
animation
’s
current finished promise
object
with
animation
Create
an
AnimationPlaybackEvent
finishEvent
Set
finishEvent
’s
type
attribute
to
finish
Set
finishEvent
’s
currentTime
attribute
to the
current time
of
animation
Set
finishEvent
’s
timelineTime
attribute
to the
current time
of the
timeline
with which
animation
is associated.
If
animation
is not associated with a timeline,
or the timeline is
inactive
let
timelineTime
be
null
If
animation
has a
document for timing
then append
finishEvent
to its
document for timing
’s
pending animation event queue
along with its target,
animation
For the
scheduled event time
use the result of
converting
animation
’s
associated effect end
to an origin-relative time.
Otherwise,
queue a task
to
dispatch
finishEvent
at
animation
The task source for this task is
the
DOM manipulation task source
If
synchronously notify
is true,
cancel any queued microtask to run
the
finish notification steps
for this
animation
and run the
finish notification steps
immediately.
Otherwise,
if
synchronously notify
is false,
queue a microtask
to run
finish notification steps
for
animation
unless there is already a microtask queued
to run those steps for
animation
If
current finished state
is false
and
animation
’s
current finished promise
is already resolved,
set
animation
’s
current finished promise
to
a new promise
in the
relevant Realm
of
animation
Typically, notification about the finished state of an animation
is performed asynchronously.
This allows for the animation to temporarily enter the
finished play state
without triggering events to be fired or promises to be resolved.
For example, in the following code fragment,
animation
temporarily enters the finished state.
If notification of the finished state occurred synchronously,
this code would cause the
finish event
to be queued
and the
current finished promise
to be resolved.
However, if we reverse the order of the two statements
such that the
iterations
is updated first,
this would not happen.
To avoid this surprising behavior,
notification about the finished state of an animation
is typically performed asynchronously.
var
animation
elem
animate
({
left
'100px'
},
2000
);
animation
playbackRate
animation
currentTime
1000
// animation is now finished
animation
effect
updateTiming
({
iterations
});
// animation is no longer finished
The one exception to this asynchronous behavior
is when the
finish an animation
procedure is performed
(typically by calling the
finish()
method).
In this case the author’s intention to finish the animation is clear
so the notification about the finished state of the animation
occurs synchronously as demonstrated below.
var
animation
elem
animate
({
left
'100px'
},
1000
);
animation
finish
();
// finish event is queued immediately and finished promise
// is resolved despite the fact that the following statement
// causes the animation to leave the finished state
animation
currentTime
Note that, like the procedure to
finish an animation
the procedure to
cancel an animation
similarly queues the
cancel event
and rejects the
current finished promise
and
current ready promise
in a
synchronous
manner.
4.5.13.
Finishing an animation
An animation can be advanced
to the natural end of its current playback direction
by using the procedure to
finish an animation
for
animation
defined below:
If
animation
’s
effective playback rate
is zero,
or if
animation
’s
effective playback rate
> 0
and
associated effect end
is infinity,
throw
an "
InvalidStateError
DOMException
and abort these steps.
Apply any pending playback rate
to
animation
Set
limit
as follows:
If
playback rate
> 0,
Let
limit
be
associated effect end
Otherwise,
Let
limit
be zero.
Silently set the current time
to
limit
If
animation
’s
start time
is
unresolved
and
animation
has an associated
active timeline
let the
start time
be the result of evaluating
timeline time
− (
limit
playback rate
where
timeline time
is the current
time value
of the associated
timeline
If there is a
pending pause task
and
start time
is
resolved
Let the
hold time
be
unresolved
Note:
Typically the
hold time
will already be unresolved
except in the case when
the animation was previously
idle
Cancel the
pending pause task
Resolve
the
current ready promise
of
animation
with
animation
If there is a
pending play task
and
start time
is
resolved
cancel that task and
resolve
the
current ready promise
of
animation
with
animation
Run the procedure to
update an animation’s finished state
for
animation
with the
did seek
flag set to true,
and the
synchronously notify
flag set to true.
4.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
The procedure to
cancel an animation
for
animation
is as follows:
If
animation
’s
play state
is
not
idle
perform the following steps:
Run the procedure to
reset an animation’s pending tasks
on
animation
Reject
the
current finished promise
with a
DOMException
named "
AbortError
".
Set the [[PromiseIsHandled]] internal slot
of the
current finished promise
to true.
Let
current finished promise
be
a new promise
in the
relevant Realm
of
animation
Create
an
AnimationPlaybackEvent
cancelEvent
Set
cancelEvent
’s
type
attribute
to
cancel
Set
cancelEvent
’s
currentTime
to
null
Let
timeline time
be the
current time
of the
timeline
with which
animation
is associated.
If
animation
is not associated with an
active timeline
let
timeline time
be an
unresolved
time value
Set
cancelEvent
’s
timelineTime
to
timeline time
If
timeline time
is
unresolved
set it to
null
If
animation
has a
document for timing
then append
cancelEvent
to
its
document for timing
’s
pending animation event queue
along with its target,
animation
If
animation
is associated with an
active timeline
that defines a procedure to
convert
timeline times to origin-relative time
let the
scheduled event time
be
the result of applying that procedure to
timeline time
Otherwise, the
scheduled event time
is
an
unresolved
time value
Otherwise,
queue a task
to
dispatch
cancelEvent
at
animation
The task source for this task is
the
DOM manipulation task source
Make
animation
’s
hold time
unresolved
Make
animation
’s
start time
unresolved
The procedure to
reset an animation’s pending tasks
for
animation
is as follows:
If
animation
does not have
pending play task
or a
pending pause task
abort this procedure.
If
animation
has a
pending play task
cancel that task.
If
animation
has a
pending pause task
cancel that task.
Apply any pending playback rate
on
animation
Reject
animation
’s
current ready promise
with a
DOMException
named "
AbortError
".
Set the [[PromiseIsHandled]] internal slot of
animation
’s
current ready promise
to true.
Let
animation
’s
current ready promise
be the result of
creating a new resolved Promise object
with value
animation
in the
relevant Realm
of
animation
4.5.15.
Speed control
The rate of play of an animation can be controlled
by setting its
playback rate
For example, setting a playback rate of 2 will cause
the animation’s
current time
to increase at twice the rate of its
timeline
Similarly, a playback rate of -1 will cause
the animation’s
current time
to decrease
at the same rate as the
time values
from its
timeline
increase.
Animations
have a
playback rate
that provides a scaling factor
from the rate of change of the associated
timeline
’s
time values
to the animation’s
current time
The
playback rate
is initially 1.
Setting an animation’s
playback rate
to zero
effectively pauses the animation
(however, the
play state
does not necessarily become
paused
).
4.5.15.1.
Setting the playback rate of an animation
The procedure to
set the playback rate
of an
animation
animation
to
new playback rate
is as follows:
Clear any
pending playback rate
on
animation
Let
previous time
be
the value of the
current time
of
animation
before changing the
playback rate
Let
previous playback rate
be
the current
effective playback rate
of
animation
Set the
playback rate
to
new playback rate
Perform the steps corresponding to
the
first
matching condition from the following, if any:
If
animation
is associated with
monotonically increasing
timeline
and the
previous time
is
resolved
Set the current time
of
animation
to
previous time
If
animation
is associated with a non-null
timeline
that is not
monotonically increasing
the
start time
of
animation
is
resolved
associated effect end
is not infinity,
and
either
the
previous playback rate
< 0
and the
new playback rate
≥ 0, or
the
previous playback rate
≥ 0
and the
new playback rate
< 0,
Set
animation
’s
start time
to the result of evaluating
associated effect end
start time
for
animation
Note:
This effectively flips the animation start/end times
on non-monotonic timelines,
preserving the relative offset of the start time
from the other direction.
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
When an
animation
animation
, is to
apply any pending playback rate
the following steps are performed:
If
animation
does not have a
pending playback rate
abort these steps.
Set
animation
’s
playback rate
to its
pending playback rate
Clear
animation
’s
pending playback rate
The procedure to
seamlessly update the playback rate
of an
animation
animation
to
new playback rate
preserving its
current time
is as follows:
Let
previous play state
be
animation
’s
play state
Note:
It is necessary to record the play state
before updating
animation
’s
effective playback rate
since,
in the following logic,
we want to immediately apply the
pending playback rate
of
animation
if it is
currently
finished
regardless of whether or not it will still be finished
after we apply the
pending playback rate
Let
animation
’s
pending playback rate
be
new playback rate
Perform the steps corresponding to
the first matching condition below:
If
animation
has a
pending play task
or a
pending pause task
Abort these steps.
Note:
The different types of pending tasks will
apply the
pending playback rate
when they run
so there is no further action required in this case.
If
previous play state
is
idle
or
paused
or
animation
’s
current time
is
unresolved
Apply any pending playback rate
on
animation
Note:
The second condition above is required
so that if we have a
running
animation
with an unresolved current time
and no pending play task,
we do not attempt to play it below.
If
previous play state
is
finished
Let the
unconstrained current time
be
the result of calculating
the
current time
of
animation
substituting an
unresolved
time value
for the
hold time
Let
animation
’s
start time
be
the result of evaluating the following expression:
timeline time
− (
unconstrained current time
pending playback rate
Where
timeline time
is the current
time value
of
the
timeline
associated with
animation
If
pending playback rate
is zero,
let
animation
’s
start time
be
timeline time
Apply any pending playback rate
on
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.
Otherwise,
Run the procedure to
play an animation
for
animation
with the
auto-rewind
flag set to false.
4.5.16.
Reversing an animation
The procedure to
reverse an animation
of
animation
animation
is as follows:
If there is no
timeline
associated with
animation
or the associated
timeline
is
inactive
throw
an "
InvalidStateError
DOMException
and abort these steps.
Let
original pending playback rate
be
animation
’s
pending playback rate
Let
animation
’s
pending playback rate
be
the additive inverse of its
effective playback rate
(i.e.
effective playback rate
).
Run the steps to
play an animation
for
animation
with the
auto-rewind
flag set to true.
If the steps to
play an animation
throw an exception,
set
animation
’s
pending playback rate
to
original pending playback rate
and propagate the exception.
4.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:
idle
The
current time
of the animation is
unresolved
and the
start time
of the animation is
unresolved
and there are no pending tasks.
In this state the animation has no effect.
running
The animation has a resolved
current time
that changes on each
animation frame
(provided the
playback rate
is not zero
and the
timeline
is
active
and
monotonically increasing
).
paused
The animation has been suspended
and the
current time
is no longer changing.
finished
The animation has reached the natural boundary of its playback range
and the
current time
is no longer updating.
The
play state
of
animation
animation
, at a given moment
is the state corresponding to
the
first
matching condition from the following:
All
of the following conditions are true:
The
current time
of
animation
is
unresolved
and
the
start time
of
animation
is
unresolved
and
animation
does
not
have
either
pending play task
or
pending pause task
idle
Either
of the following conditions are true:
animation
has a
pending pause task
or
both
the
start time
of
animation
is
unresolved
and
it does
not
have a
pending play task
paused
For
animation
current time
is
resolved
and
either
of the following conditions are true:
animation
’s
effective playback rate
> 0
and
current time
associated effect end
or
animation
’s
effective playback rate
< 0 and
current time
≤ 0,
finished
Otherwise,
running
Note that the
paused play state
effectively “wins”
over the
finished play state
However, an animation that is paused
outside of its natural playback range
can be converted from a
paused
animation
into a
finished
animation
without restarting by setting the
start time
such as below:
animation
effect
updateTiming
({
duration
5000
});
animation
currentTime
4000
animation
pause
();
animation
ready
then
function
()
animation
effect
updateTiming
({
duration
3000
});
alert
animation
playState
);
// Displays 'paused'
animation
startTime
document
timeline
currentTime
animation
currentTime
animation
playbackRate
alert
animation
playState
);
// Displays 'finished'
});
4.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.
To
convert
an animation time to timeline time
time value
time
, that is relative to
the
start time
of an animation,
animation
perform the following steps:
If
time
is
unresolved
return
time
If
time
is infinity,
return an
unresolved
time value
If
animation
’s
playback rate
is zero,
return an
unresolved
time value
If
animation
’s
start time
is
unresolved
return an
unresolved
time value
Return the result of calculating
time
× (1 /
playback rate
) +
start time
where
playback rate
and
start time
are
the
playback rate
and
start time
of
animation
respectively.
To
convert
a timeline time to an origin-relative time
time value
time
, that is expressed in the same scale
as the
time values
of a
timeline
timeline
perform the following steps:
Let
timeline time
be the result of
converting
time
from an animation time to a timeline time.
If
timeline time
is
unresolved
return
time
If
animation
is not associated with a
timeline
return an
unresolved
time value.
If
animation
is associated with an
inactive timeline
return an
unresolved
time value.
If there is no procedure
to
convert
a timeline time to an origin-relative time
for the timeline associated with
animation
return an
unresolved
time value
Return the result of
converting
timeline time
to an origin-relative time
using the procedure defined for
the
timeline
associated with
animation
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
playback direction
applying to each iteration,
to allow reversing the timing of effects within an iteration
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:
If the
animation effect
is
associated with an animation
the
local time
is the
current time
of the
animation
Otherwise,
the
local time
is
unresolved
4.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.
A comparison of
local time
active time
, and
iteration time
for an animation with an
iteration duration
of 1s
and an
iteration count
of 2.5.
The
start time
defined by the
animation
and
end time
defined by the
animation effect
are also annotated.
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.
Examples of the effect of the
start delay
on the endpoints of the
active interval
(a) An animation effect with no delay;
the
start time
and beginning of the
active interval
are coincident.
(b) An animation effect with a positive delay;
the beginning of the
active interval
is deferred by the delay.
(c) An animation effect with a negative delay;
the beginning of the
active interval
is brought forward by the delay.
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.
An example of the different phases and states
used to describe an
animation effect
The phases are as follows:
before phase
The
animation effect
’s
local time
falls before
the effect’s
active interval
and
end time
or
occurs during the range when a negative
start delay
is in effect.
active phase
The
animation effect
’s
local time
falls
inside the effect’s
active interval
and outside the range of any negative
start delay
or negative
end delay
after phase
The
animation effect
’s
local time
falls
after the effect’s
active interval
or after the
end time
if that comes first
(due to a negative
end delay
),
but
not
during the range when a negative
start delay
is in effect.
In addition to these phases,
an
animation effect
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)
Furthermore, an
endpoint-inclusive active interval
flag
may be specified when determining the phase.
If not specified, it is assumed to be false.
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”,
the
endpoint-inclusive active interval
flag is false,
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”,
the
endpoint-inclusive active interval
flag is false,
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
The
relevant animations
for an element or pseudo-element
target
is the set of all
animations
that contain
at least one
animation effect
whose
effect target
is
target
The
relevant animations for a subtree
of an element, pseudo-element,
document
, or
shadow root
target
is the set of all
animations
that contain at least one
animation effect
whose
effect target
is an
inclusive descendant
(or
descendant
, if
target
is a
document
or
shadow root
of
target
or is a
pseudo-element
of such a descendant.
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.
Examples of various fill modes and the states produced.
(a) fill mode
none
The animation effect has no effect outside its active phase.
(b) fill mode
forwards
After the active phase has finished,
the
iteration progress
value continues to maintain a fill value.
(c) fill mode
backwards
The animation effect produces a fill value
until the start of the active phase.
(d) fill mode
both
Both before and after the active phase
the animation effect produces a fill value.
Note:
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.
This can be achieved by waiting for the animation to finish
and then updating the style as illustrated below:
// In the first frame after the following animation finishes,
// the callback for the `finished` promise will run
// BEFORE style is updated, and hence will NOT flicker.
elem
animate
({
transform
'translateY(100px)'
},
200
).
finished
then
(()
=>
elem
style
transform
'translateY(100px)'
});
More conveniently, an
Animation
’s
commitStyles
method can
be used to produce the same effect.
elem
animate
({
transform
'translateY(100px)'
},
200
).
finished
then
(()
=>
elem
commitStyles
();
});
Alternatively, the author can set the specified style
at the start of the animation and then animate
from
the original value as illustrated below:
elem
style
transform
'translateY(100px)'
elem
animate
({
transform
'none'
offset
},
200
);
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.
A comparison of the
iteration duration
and
active duration
of an animation effect with an
iteration count
of 2.5.
Note that the
iteration duration
for the final iteration
does not change; it is simply cut-off by the
active duration
4.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.
The effect of the
iteration count
and
iteration start
parameters.
In the first case the
iteration count
is 2.5
resulting in the third iteration being cut off
halfway through its
iteration interval
The second case is the same
but with an
iteration start
of 0.5.
This causes the
animation effect
to begin
halfway through the first iteration.
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.
Illustration of end-point exclusive timing.
For both repeated and sequenced animation effects
there is no overlap at the boundaries between intervals.
An exception to this behavior is that
when performing a
fill
if the fill begins at an interval endpoint,
the endpoint is used.
This behavior falls out of the algorithm given in
§ 4.7.4 Calculating the simple iteration progress
and is illustrated below.
After one iteration, the
iteration progress
is 0,
but after two iterations (and there onwards),
the
iteration progress
is 1
due to the special behavior defined when an animation effect fills.
4.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
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.
Calculation of the
active duration
is based on multiplying the
iteration duration
by the
iteration count
Having established the
active duration
the process for transforming an
animation effect
’s
local time
into its
transformed progress
iteration progress
is illustrated below.
An overview of timing model calculations.
(1) The
local time
is determined from the associated
animation
(2) The
local time
is converted into an
active time
by incorporating the
start delay
(3) The
active time
is divided by the
iteration duration
incorporating also the
iteration start
property
to produce the
overall progress
(4) The
overall progress
time is then converted
to an offset within a single iteration:
the
simple iteration progress
(5) The
simple iteration progress
is converted
into a
directed progress
by incorporating the
playback direction
(6) Finally, an
easing function
is applied to the
directed progress
to produce the
transformed progress
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
both
Return the result of evaluating
max(min(
local time
start delay
active duration
),
0)
Otherwise,
Return an
unresolved
time value
Otherwise (the
local time
is
unresolved
),
Return an
unresolved
time value
4.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:
If the
active time
is
unresolved
return
unresolved
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
Return the result of calculating
overall progress
iteration start
Tests
overallProgress.html
(live test)
(source)
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:
If the
overall progress
is
unresolved
return
unresolved
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
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.
Return
simple iteration progress
4.7.5.
Calculating the
current iteration index
The
current iteration index
can be calculated
using the following steps:
If the
active time
is
unresolved
return
unresolved
If the animation effect is in the
after phase
and
the
iteration count
is infinity,
return infinity.
If the
simple iteration progress
is 1.0,
return
floor(
overall progress
) − 1
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:
If the
simple iteration progress
is
unresolved
return
unresolved
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,
Let
be the
current iteration index
If
playback direction
is
alternate-reverse
increment
by 1.
If
% 2 == 0
let the
current direction
be forwards;
otherwise let the
current direction
be reverse.
If
is infinity,
let the
current direction
be forwards.
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:
If the
directed progress
is
unresolved
return
unresolved
Calculate the value of the
before flag
as follows:
Determine the
current direction
using
the procedure defined in
§ 4.7.6 Calculating the directed progress
If the
current direction
is
forwards
let
going forwards
be true; otherwise it is false.
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.
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
This section is non-normative
For some kinds of
animation effects
the
Web Animations
animation model
takes the
iteration progress
and
iteration index
values
produced by the
timing model
and uses them to calculate a corresponding output.
The output of each such animation effect
is then combined with that of others using an
effect stack
before being applied to the
target properties
(see
§ 5.4 Combining effects
).
5.1.
Introduction
An
animation effect
has zero or more associated properties
that it affects in response to changes to its timing output.
These properties are referred to as the effect’s
target properties
Given an
iteration progress
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
to
at 50% (
p=0.5
),
i.e.
result
start
if
0.5
end
if
0.5
by computed value
Corresponding individual components of the
computed values
are combined (interpolated, added, or accumulated)
using the indicated procedure for that value type
(see
CSS Values 4
§ 3 Combining Values: Interpolation, Addition, and Accumulation
).
If the number of components or the types of corresponding components
do not match,
or if any component value uses
discrete
animation
and the two corresponding values do not match,
then the property values combine as
discrete
repeatable list
Same as
by computed value
except that if the two lists have differing numbers of items,
they are first repeated to the least common multiple number of items.
Each item is then combined
by computed value
If a pair of values cannot be combined
or if any component value uses
discrete
animation,
then the property values combine as
discrete
Note:
The repeatable list concept ensures that
a list that is conceptually repeated to a certain length
(as
background-origin
is repeated to the length of
the
background-image
list)
or repeated infinitely
will smoothly transition between any values,
and so that the computed value
will properly represent the result
(and potentially be inherited correctly).
(See prose)
Some properties have specific interpolation behavior
not covered by the above cases;
in this case the animation behavior will be specified explicitly
for that property.
The
animation type
of properties that do not yet include
an
Animation type
line in their property definition,
is defined in
Appendix A: Animation types of existing properties
5.2.1.
Custom Properties
For
custom properties
registered using
the
registerProperty()
method for the
current global object
the
animation type
is
by computed value
derived from the type used in the property’s
syntax definition
Where there is no
computed value
type that corresponds
to the property’s specified syntax
(e.g. when the syntax is the
universal syntax definition
or when the
custom property
is not registered,
the
animation type
is
discrete
5.3.
Keyframe effects
Keyframe effects
are a kind of
animation effect
that 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.
Tests
applying-interpolated-transform.html
(live test)
(source)
5.3.2.
Computing property values
To
compute a property value
given a property
property
a value
value
and an
Element
element
resolve
value
according to the “Computed Value” line
of the
property
’s definition table,
using the
computed values
of
element
as the context for resolving dependencies,
and return the result.
Note:
The
computed values
on
element
are not affected by this algorithm.
This algorithm implies that property values specified in keyframes
can establish order dependencies.
When
computing a property value
the
computed values
of dependencies held by
value
must be calculated
first
var
animation
elem
animate
([{
fontSize
'10px'
width
'10em'
},
fontSize
'20px'
width
'20em'
}],
1000
);
animation
currentTime
500
console
log
getComputedStyle
elem
).
fontSize
);
// Should be 15px
console
log
getComputedStyle
elem
).
width
);
// Should be 225px
In this example,
in order to
compute a property value
for
10em
we need to know the
computed value
of
font-size
on the
target element
which in turn is determined by the
effect value
for
font-size
which in turn depends on computing property values for
font-size
Hence, computing property values are subject to ordering constraints.
5.3.3.
Calculating computed keyframes
Before calculating the
effect value
of a
keyframe effect
the property values on its
keyframes
are
computed
and the offset to use for any keyframes with a null
keyframe offset
is computed.
The result of resolving these values
is a set of
computed keyframes
The calculated
keyframe offsets
of a set of
keyframe
that includes suitable values
for each null
keyframe offset
are referred to as the
computed keyframe offsets
To produce
computed keyframe offsets
we define a procedure to
compute missing keyframe offsets
that takes a sequence of
keyframes
keyframes
and has the following steps:
For each
keyframe
in
keyframes
let the
computed keyframe offset
of the
keyframe
be equal to its
keyframe offset
value.
If
keyframes
contains more than one
keyframe
and the
computed keyframe offset
of the first
keyframe
in
keyframes
is null,
set the
computed keyframe offset
of the first
keyframe
to 0.
If the
computed keyframe offset
of the last
keyframe
in
keyframes
is null,
set its
computed keyframe offset
to 1.
For each pair of
keyframes
and
where:
appears before
in
keyframes
, and
and
have a
computed keyframe offset
that is not null, and
all
keyframes
between
and
have a null
computed keyframe offset
calculate the
computed keyframe offset
of each
keyframe
between
and
as follows:
Let
offset
be
the
computed keyframe offset
of a
keyframe
Let
be
the number of keyframes
between
and including
and
minus 1.
Let
index
refer to the position
of
keyframe
in the sequence of keyframes between
and
such that the first keyframe after
has an
index
of 1.
Set the
computed keyframe offset
of
keyframe
to
offset
offset
offset
index
Tests
background-shorthand.html
(live test)
(source)
computed-keyframes-shorthands.html
(live test)
(source)
effect-value-context-filling.html
(live test)
(source)
effect-value-context.html
(live test)
(source)
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.
Let
computed keyframes
be an empty list of
keyframes
For each
keyframe
in the list of
keyframes
specified on this
keyframe effect
perform the following steps:
Add a new empty
keyframe
computed keyframe
to
computed keyframes
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:
Longhand properties override shorthand properties
(e.g.
border-top-color
overrides
border-top
).
Shorthand properties with fewer longhand components
override those with more longhand components
(e.g.
border-top
overrides
border-color
).
Physical properties override logical properties.
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.
Apply the procedure to
compute missing keyframe offsets
to
computed keyframes
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.
If
iteration progress
is
unresolved
abort this procedure.
Let
target property
be the
longhand property
for which the
effect value
is to be calculated.
If
animation type
of the
target property
is
not animatable
abort this procedure since the effect cannot be applied.
If the
keyframe effect
does not have an
effect target
or if the
effect target
cannot have computed property values calculated,
abort this procedure.
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
Let
property-specific keyframes
be
the result of getting the set of
computed keyframes
for this
keyframe effect
Remove any
keyframes
from
property-specific keyframes
that do not have a property value for
target property
If
property-specific keyframes
is empty,
return
underlying value
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
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
Let
interval endpoints
be an empty sequence of keyframes.
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,
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.
Append to
interval endpoints
the next
keyframe
in
property-specific keyframes
after the one added in the previous step.
For each
keyframe
in
interval endpoints
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:
Let
composite operation to use
be
the
composite operation
of
keyframe
or if it has none,
the
composite operation
of this
keyframe effect
Let
value to combine
be
the property value of
target property
specified on
keyframe
Replace the property value of
target property
on
keyframe
with the result of combining
underlying value
) and
value to combine
using the procedure for the
composite operation to use
corresponding to the
target property
’s
animation type
If there is only one keyframe in
interval endpoints
return the property value of
target property
on that keyframe.
Let
start offset
be the
computed keyframe offset
of the first keyframe in
interval endpoints
Let
end offset
be the
computed keyframe offset
of last keyframe in
interval endpoints
Let
interval distance
be the result of evaluating
iteration progress
start offset
/ (
end offset
start offset
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.
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
start
and the second as
end
and using
transformed distance
as the interpolation parameter
Tests
effect-value-interval-distance.html
(live test)
(source)
effect-value-iteration-composite-operation.html
(live test)
(source)
effect-value-opacity-replaced-effect-in-shadow-root.html
(live test)
(source)
effect-value-opacity-replaced-effect.html
(live test)
(source)
effect-value-overlapping-keyframes.html
(live test)
(source)
effect-value-replaced-animations.html
(live test)
(source)
effect-value-transformed-distance.html
(live test)
(source)
Note that this procedure assumes the following
about the list of
keyframes
specified on the effect:
Each
keyframe
has a specified
computed keyframe offset
in the range [0, 1].
The list of
keyframes
is sorted in ascending order
by
computed keyframe offset
For a given property,
there is at most one specified property value on each keyframe.
It is the responsibility of the user of the model
(for example, a declarative markup or programming interface)
to ensure these conditions are met.
For example, for the
programming interface
defined by this specification,
these conditions are met by
the procedure to produce the
computed keyframes
that become the input to this procedure.
Note:
this procedure permits overlapping
keyframes
The behavior is that
at the point of overlap the output value jumps
to the value of the last defined
keyframe
at that offset.
For overlapping keyframes at 0 or 1,
the output value for
iteration progress
values
less than 0 or greater than or equal to 1
is the value of
the first
keyframe
or the last
keyframe
in
keyframes
respectively.
Note that
computed keyframes
are “live”:
user-agents behave as if they are recreated
every time the
effect value
is calculated.
For example, if there is an ongoing transition
on the
font-size
property from
10px
to
20px
a property value specified as
1em
in a
keyframe
would during
keyframe computation
resolve against the
computed value
in the range [
10px
20px
produced by the transition on
font-size
In the presence of certain easing functions,
the input
iteration progress
to an animation effect
is not limited to the range [0, 1].
Currently, however, keyframe offsets
are
limited to the range [0, 1]
and property values are simply extrapolated
for input
iteration progress
values outside this range.
We have considered removing this restriction
since some cases exist where it is useful
to be able to specify non-linear changes in property values
at
iteration progress
values outside the range [0, 1].
One example is an animation that interpolates from green to yellow
but has an overshoot easing function
that makes it temporarily interpolate “beyond” yellow to red
before settling back to yellow.
While this effect could be achieved by
modification of the keyframes and easing function,
this approach seems to break the model’s separation
of timing concerns from animation effects.
It is not clear how this effect should be achieved
but we note that allowing keyframe offsets outside [0, 1]
can make the currently specified behavior,
where keyframes at offset 0 and 1 are synthesized as necessary,
inconsistent.
See
section 4
(Keyframe offsets outside [0, 1]) of minuted discussion from Tokyo 2013 F2F

5.4.
Combining effects
This section is non-normative
After calculating the
effect values
for a
keyframe effect
they are applied to the
animation effect
’s
target properties
Since it is possible for multiple
in effect
keyframe effects
to target the same property
it is often necessary to combine the results
of several
keyframe effects
together.
This process is called
compositing
and is based on establishing an
effect stack
for each property targeted by an
in effect
animation effect
After
compositing
the results of
keyframe effects
together,
the composited result
is combined with other values specified for the
target property
The arrangement is illustrated below:
Overview of the application of
effect values
to their
target properties
The results of
keyframe effects
targeting the same property
are composited together using an
effect stack
The result of this composition is then inserted into the CSS cascade
at an appropriate point.
For the first part of this operation—​combining
effect values
that target the same
property
—​it is necessary to determine both
how
keyframe effects
are combined with one another,
as well as the
order
in which they are applied,
that is, their relative
composite order
The matter of
how
effect values
are combined
is governed by the
composite operation
of the corresponding
keyframe effects
The relative
composite order
of
effect values
is determined by an
effect stack
established for each animated property.
5.4.1.
Animation classes
This specification provides a common animation model
intended to be used by other specifications
that define markup or programming interfaces on top of this model.
The particular markup or programming interface
that generated an
animation
defines its
animation class
Further specifications may define specialized behavior for composite ordering
between different classes of animations or within a particular class.
This section is non-normative
For example, animations whose
class
is “CSS animation”
are defined as having a
higher
composite order
than animations whose class is “CSS transition”
but
lower
than other animations without a specific class.
Within the set of “CSS animation” objects,
specialized composite ordering is defined
based on the
animation-name
property
amongst other factors.
5.4.2.
The effect stack
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
and
within an
effect stack
is established by comparing their properties as follows:
Sort
and
by applying the following conditions in turn
until the order is resolved,
If
and
’s
associated animations
differ
by
class
sort by any inter-class composite order
as defined for the corresponding classes.
If
and
are still not sorted,
sort by any
class
-specific composite order
defined by the common class of
and
’s
associated animations
If
and
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 an
underlying value
is determined by the
composite operation
of the
keyframe effect
that produced the
effect value
This specification defines three
composite operations
as follows:
replace
The result of compositing the
effect value
with the
underlying value
is simply the
effect value
add
The
effect value
is
added
to the
underlying value
For
animation types
where the
addition operation
is defined such that it is not commutative,
the order of the operands is
underlying value
effect value
accumulate
The
effect value
is
accumulated
onto the
underlying value
For
animation types
where the
accumulation operation
is defined such that it is not commutative,
the order of the operands is
underlying value
followed by
effect value
Tests
effect-composition.html
(live test)
(source)
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]
Tests
applying-the-composited-result.html
(live test)
(source)
For example, if the effect with the highest composite order
is associated with a “CSS transition”-class animation,
the
composited value
will be added to
the
Transition Origin
of the cascade.
The
composited value
calculated for a CSS
target property
is applied using the following process:
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.
Establish the
effect stack
for the property
(see
§ 5.4.2 The effect stack
).
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
).
Insert the
composited value
into the CSS cascade
at the level defined for the
class
of
the
animation
associated with
the effect at the top of the
effect stack
established for the
target property
5.5.
Replacing animations
This section is non-normative
Using the programming interface defined in this specification,
it is possible to repeatedly trigger new animations
that contribute to an element’s animated style indefinitely.
For example, consider the following code:
elem
addEventListener
'mousemove'
evt
=>
circle
animate
transform
`translate(
${
evt
clientX
px,
${
evt
clientY
px)`
},
duration
500
fill
'forwards'
);
});
This will generate a new forwards-filling animation
each time the mouse is moved,
quickly producing hundreds, even thousands of forwards-filling animations.
If the user agent needed to retain
all
such animations,
the list of animations would grow in an unbounded fashion,
producing a memory leak.
This section defines a mechanism
that causes overridden animations to be automatically removed
unless the author explicitly requests they be retained.
5.5.1.
Replace state
An
animation
maintains a
replace state
that 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
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:
Set
animation
’s
replace state
to
removed
Create
an
AnimationPlaybackEvent
removeEvent
Set
removeEvent
’s
type
attribute to
remove
Set
removeEvent
’s
currentTime
attribute
to the
current time
of
animation
Set
removeEvent
’s
timelineTime
attribute
to the
current time
of the
timeline
with which
animation
is associated.
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.
Tests
side-effects-of-animations-current.html
(live test)
(source)
side-effects-of-animations-in-effect.html
(live test)
(source)
side-effects-of-animations-none.html
(live test)
(source)
Note:
As a result of the above requirement,
if an animation targets, for example,
the
transform
property of an element,
stacking context
will be created for the
effect target
so long as the
animation
is in the
before phase
the
active phase
or,
if it has a
fill mode
of
forwards
or
both
the
after phase
6.
Programming interface
This section is non-normative
In addition to the abstract model described above,
Web Animations also defines a programming interface to the model.
This interface can be used
to inspect and extend animations produced by declarative means
or for directly producing animations
when a procedural approach is more suitable.
6.1.
Time values in the programming interface
Time values
are represented in the programming interface
with the type
double
Unresolved
time values are represented
by the value
null
6.2.
The
AnimationTimeline
interface
Timelines
are represented in the Web Animations API
by the
AnimationTimeline
interface.
Exposed
Window
interface
AnimationTimeline
readonly
attribute
double
currentTime
};
currentTime
of type
double
, readonly, nullable
Returns the
current time
for this timeline
or
null
if this timeline is
inactive
6.3.
The
DocumentTimeline
interface
Document timelines
including the
default document timeline
are represented in the Web Animations API
by the
DocumentTimeline
interface.
dictionary
DocumentTimelineOptions
DOMHighResTimeStamp
originTime
= 0;
};

Exposed
Window
interface
DocumentTimeline
AnimationTimeline
constructor
optional
DocumentTimelineOptions
options
= {});
};
originTime
of type
DOMHighResTimeStamp
, defaulting to
The
origin time
for the timeline
specified as a real number of milliseconds
relative to the
time origin
DocumentTimeline (
options
Creates a new
DocumentTimeline
The
Document
with which the timeline is associated
is the
Document
associated
with the
Window
that is the
current global object
options
Configuration parameters for the newly-created timeline.
This specification defines only the
originTime
member
but other specifications may extend this set.
6.4.
The
Animation
interface
Animations
are represented in the Web Animations API
by the
Animation
interface.
Exposed
Window
interface
Animation
EventTarget
constructor
optional
AnimationEffect
effect
null
optional
AnimationTimeline
timeline
);
attribute
DOMString
id
attribute
AnimationEffect
effect
attribute
AnimationTimeline
timeline
attribute
double
startTime
attribute
double
currentTime
attribute
double
playbackRate
readonly
attribute
AnimationPlayState
playState
readonly
attribute
AnimationReplaceState
replaceState
readonly
attribute
boolean
pending
readonly
attribute
Promise
Animation
ready
readonly
attribute
Promise
Animation
finished
attribute
EventHandler
onfinish
attribute
EventHandler
oncancel
attribute
EventHandler
onremove
undefined
cancel
();
undefined
finish
();
undefined
play
();
undefined
pause
();
undefined
updatePlaybackRate
double
playbackRate
);
undefined
reverse
();
undefined
persist
();
CEReactions
undefined
commitStyles
();
};
Animation (
effect
timeline
Creates a new
Animation
object using the following procedure:
Let
animation
be a new
Animation
object.
Run the procedure to
set the timeline of an animation
on
animation
passing
timeline
as the
new timeline
or, if the
timeline
argument is missing,
passing the
default document timeline
of the
Document
associated
with the
Window
that is the
current global object
Run the procedure to
set the associated effect of an animation
on
animation
passing
source
as the
new effect
effect
An optional value which, if not
null
specifies the
associated effect
to assign
to the newly created
animation
timeline
An optional value which, if present,
specifies the
timeline
with which to associate
the newly-created
animation
If missing, the
default document timeline
of the
Document
associated
with the
Window
that is the
current global object
is used.
Tests
constructor.html
(live test)
(source)
id
of type
DOMString
A string used to identify the animation.
Tests
id.html
(live test)
(source)
effect
of type
AnimationEffect
, nullable
The
associated effect
of this animation.
Setting this attribute updates the object’s
associated effect
using the procedure to
set the associated effect of an animation
Tests
effect.html
(live test)
(source)
timeline
of type
AnimationTimeline
, nullable
The
timeline
associated with this animation.
Setting this attribute updates the object’s
timeline
using the procedure to
set the timeline of an animation
startTime
of type
double
, nullable
Returns the
start time
of this animation.
Setting this attribute updates the
start time
using the procedure to
set the start time
of this object to the new value.
currentTime
of type
double
, nullable
The
current time
of this animation.
Setting this attribute follows the procedure to
set the current time
of this object to the new value.
playbackRate
of type
double
The
playback rate
of this animation.
Setting this attribute follows the procedure to
set the playback rate
of this object to the new value.
Setting this attribute performs
a synchronous update to the
playback rate
meaning that it does not make any attempt
to synchronize with the playback state of animations running
on a separate process or thread.
As a result, setting the
playbackRate
for an in-flight animation
can cause it to jump.
To set the
playback rate
for an in-flight animation
such that it smoothly updates,
use the asynchronous
updatePlaybackRate()
method.
playState
of type
AnimationPlayState
, readonly
The
play state
of this animation.
replaceState
of type
AnimationReplaceState
, readonly
The
replace state
of this animation.
pending
of type
boolean
, readonly
Returns true if this animation has
pending play task
or a
pending pause task
Tests
pending.html
(live test)
(source)
ready
of type Promise<
Animation
>, readonly
Returns the
current ready promise
for this object.
Tests
ready.html
(live test)
(source)
finished
of type Promise<
Animation
>, readonly
Returns the
current finished promise
for this object.
Tests
finished.html
(live test)
(source)
onfinish
of type
EventHandler
The event handler for the
finish event
Tests
onfinish.html
(live test)
(source)
oncancel
of type
EventHandler
The event handler for the
cancel event
Tests
oncancel.html
(live test)
(source)
onremove
of type
EventHandler
The event handler for the
remove event
Tests
onremove.html
(live test)
(source)
void cancel()
Clears all effects caused by this animation
and aborts its playback by running the
cancel an animation
procedure
for this object.
Tests
cancel.html
(live test)
(source)
void finish()
Seeks
the animation to
the
associated effect end
in the current direction
by running the
finish an animation
procedure
for this object.
DOMException
of type "
InvalidStateError
Raised if this animation’s
playback rate
is zero,
or if this animation’s
playback rate
is > zero
and the
associated effect end
is infinity.
void play()
Begins or resumes playback of the animation
by running the procedure to
play an animation
passing true as the value of the
auto-rewind
flag.
void pause()
Suspends the playback of this animation
by running the procedure to
pause an animation
for this object.
Tests
pause.html
(live test)
(source)
void updatePlaybackRate(
playbackRate
Performs an asynchronous update of the
playback rate
of this animation
by performing the
seamlessly update the playback rate
procedure,
passing
playbackRate
as the
new playback rate
playbackRate
A finite real number specifying
the updated playback rate to use.
void reverse()
Inverts the
playback rate
of this animation
and plays it using the
reverse an animation
procedure
for this object.
As with
play()
this method unpauses the animation and,
if the animation has already finished playing in the reversed direction,
seeks
to the start of the
associated effect
void persist()
Sets this animation’s
replace state
to
persisted
void commitStyles()
Writes the current
effect values
produced by this animation’s
animation effects
to their corresponding
effect targets
' inline style
using the
commit computed styles
procedure.
Unlike most other methods defined on this interface,
calling this method
does
trigger a
style change event
(see
§ 6.13 Model liveness
).
Tests
commitStyles.html
(live test)
(source)
In order to simplify the common case
of persisting a completed animation,
the procedure to
commit computed styles
uses endpoint-
inclusive
timing (see
§ 4.6.9.3 Interval timing
when determining the phase of the animation
(see
§ 4.6.6 Animation effect phases and states
).
As a result, the following code will persist
the
transform: translateY(100px)
style in specified style
despite not having a
fill mode
of
forwards
or
both
elem
animate
({
transform
'translateY(100px)'
},
200
).
finished
then
(()
=>
elem
commitStyles
();
});
Since the procedure to
commit computed styles
includes the
effect values
for the animation
even if it is
removed
this method is useful for retaining the effect of an animation
after it has been replaced (see
§ 5.5.2 Removing replaced animations
without retaining the actual animation.
Note that the values committed are the
computed
values
produced by the
animation effects
at the time when this method is called.
Since these values are computed values,
they do not reflect to changes to context
such as responding to changes to CSS variables
or recalculating
em
units
based on changes to the computed
font-size
in the way the values produced by a live animation would.
In order to retain full fidelity of a filling animation’s result
after it has been replaced (see
§ 5.5 Replacing animations
),
the
persist()
method can be used,
but note that doing so will mean
the animation continues to consume resources.
To
commit computed styles
for an
animation
animation
Let
targets
be the
set
of all
effect targets
for
animation effects
associated
with
animation
For each
target
in
targets
If
target
is not an element capable of having
style attribute
[CSS-STYLE-ATTR]
(for example, it is a
pseudo-element
or is an element in a document format
for which style attributes are not defined)
throw
a "
NoModificationAllowedError
DOMException
and abort these steps.
If, after applying any pending style changes,
target
is not
being rendered
throw
an "
InvalidStateError
DOMException
and abort these steps.
The definition of
being rendered
[HTML]
with regards to
display: contents
is still
under discussion
For the purpose of this procedure,
we assume that an element with
display: contents
that otherwise would have associated layout boxes
(i.e. it is
connected
and not part of a
display: none
subtree)
is
being rendered.
Let
inline style
be the result
of getting the
CSS declaration block
corresponding to
target
’s
style attribute
If
target
does not
have
style attribute
let
inline style
be a new empty
CSS declaration block
with the
owner node
set to
target
Let
targeted properties
be the
set
of physical longhand properties
that are a
target property
for at least one
animation effect
associated
with
animation
whose
effect target
is
target
For each property,
property
, in
targeted properties
Let
partialEffectStack
be a copy of the
effect stack
for
property
on
target
If
animation
’s
replace state
is
removed
add all
animation effects
associated
with
animation
whose
effect target
is
target
and that include
property
as a
target property
to
partialEffectStack
Remove from
partialEffectStack
any
animation effects
whose
associated
animation
has a higher
composite order
than
animation
Let
effect value
be the result of calculating
the result of
partialEffectStack
for
property
using
target
’s computed style
(see
§ 5.4.3 Calculating the result of an effect stack
) and
setting the
endpoint-inclusive active interval
flag
to true
when calculating the animation effect phase
(see
§ 4.6.6 Animation effect phases and states
).
Set a CSS declaration
of
property
for
effect value
in
inline style
Update style attribute for
inline style
6.4.1.
The
AnimationPlayState
enumeration
enum
AnimationPlayState
"idle"
"running"
"paused"
"finished"
};
idle
Corresponds to the
idle play state
running
Corresponds to the
running play state
paused
Corresponds to the
paused play state
finished
Corresponds to the
finished play state
6.4.2.
The
AnimationReplaceState
enumeration
enum
AnimationReplaceState
"active"
"removed"
"persisted"
};
active
Corresponds to the
active replace state
removed
Corresponds to the
removed replace state
persisted
Corresponds to the
persisted replace state
6.5.
The
AnimationEffect
interface
Animation effects
are represented in the Web Animations API by the
abstract
AnimationEffect
interface.
Exposed
Window
interface
AnimationEffect
EffectTiming
getTiming
();
ComputedEffectTiming
getComputedTiming
();
undefined
updateTiming
optional
OptionalEffectTiming
timing
= {});
};
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.
getTiming()
Returns the specified timing properties
for this
animation effect
For the correspondence between
the members of the returned
EffectTiming
object
and properties of the
timing model
see the
EffectTiming
interface.
getComputedTiming()
Returns the calculated timing properties
for this
animation effect
Although some of the attributes
of the object returned by
getTiming()
and
getComputedTiming()
are common,
their values can differ in the following ways:
duration
while
getTiming()
can return
the string
auto
getComputedTiming()
must return
a number corresponding to
the calculated value of the
iteration duration
as defined in the description of
the
duration
member of the
EffectTiming
interface.
In this level of the specification, that simply means that an
auto
value is replaced by zero.
fill
likewise, while
getTiming()
can return
the string
auto
getComputedTiming()
must return
the specific
FillMode
used for timing calculations
as defined in the description of
the
fill
member of the
EffectTiming
interface.
In this level of the specification,
that simply means that an
auto
value is replaced
by the
none
FillMode
Note:
It is likely that other timing members
could be extended in future to include
auto
-like values.
When performing timing calculations,
authors are encouraged
to use
getComputedTiming()
where possible
to avoid incompatibility
should the range or type of allowed specified values be changed.
In addition to possible differences in the values returned,
compared to
getTiming()
getComputedTiming()
returns
additional timing information
as defined by the
ComputedEffectTiming
dictionary.
updateTiming(
timing
Updates the specified timing properties of this
animation effect
by performing the procedure to
update the timing properties of an animation effect
passing the
timing
parameter
as
input
optional
OptionalEffectTiming
timing
The timing properties to update.
The timing properties corresponding to any members
that do not
exist
on
timing
will
not
be modified.
The
remove()
method can be used to remove an effect
from either its parent group or animation.
Should we keep it in level 1 and define it simply
as removing the animation effect from its animation?
[Issue #2082]
6.5.1.
The
EffectTiming
and
OptionalEffectTiming
dictionaries
The
EffectTiming
dictionary represents
the timing properties of an
AnimationEffect
The
OptionalEffectTiming
dictionary
is a variant of the
EffectTiming
dictionary
that allows some members to 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
};
delay
of type
double
, defaulting to
The
start delay
which represents the number of milliseconds
from the
start time
of the associated
animation
to the start of the
active interval
endDelay
of type
double
, defaulting to
The
end delay
which represents the number of milliseconds
from the end of an
animation effect
’s
active interval
until its
end time
fill
of type
FillMode
, defaulting to
"auto"
The
fill mode
which defines the behavior of the
animation effect
outside its
active interval
When performing timing calculations
the special string value
auto
is expanded
to one of the
fill modes
recognized by the timing model
as follows:
If the
animation effect
to which the fill mode is being applied
is a
keyframe effect
Use
none
as the
fill mode
Otherwise,
Use
both
as the
fill mode
As described in
§ 4.6.8 Fill behavior and fill modes
authors are discouraged from using indefinitely filling animations.
iterationStart
of type
double
, defaulting to
0.0
The
animation effect
’s
iteration start
property,
which is a finite real number greater than or equal to zero
representing the
iteration index
at which the
animation effect
begins
and its progress through that iteration.
For example, a value of 0.5 indicates that
the animation effect begins halfway through its first iteration.
A value of 1.2 indicates the animation effect begins
20% of the way through its second iteration.
Note that the value of
iterations
is effectively
added
to the
iterationStart
such that an animation effect with
an
iterationStart
of "0.5"
and
iterations
of "2"
will still repeat twice.
However it will begin and end halfway through
its
iteration interval
iterationStart
values greater than or equal to 1
are typically only useful in combination with an animation effect
that has an
iteration composite operation
of
accumulate
or when the
current iteration index
is otherwise significant.
iterations
of type
unrestricted double
, defaulting to
1.0
The
animation effect
’s
iteration count
property
which is a real number greater than or equal to zero
(including positive infinity)
representing the number of times to the animation effect repeats.
This can be set to
+Infinity
to cause the
animation effect
to repeat forever
(unless the duration of the effect is zero,
in which case it will finish immediately).
duration
of type
(unrestricted double or DOMString)
, defaulting to
"auto"
The
iteration duration
which is a real number greater than or equal to zero
(including positive infinity)
representing the time taken to complete
a single iteration of the
animation effect
In this level of this specification,
the string value
auto
is treated as the value zero
for the purpose of timing model calculations
and for the result of the
duration
member
returned from
getComputedTiming()
If the author specifies the
auto
value,
user agents must, however, return
auto
for the
duration
member
returned from
getTiming()
Note:
This is a forwards-compatibility measure
since a future level of this specification
is expected to introduce group effects
where the
auto
value expands
to include the duration of the child effects.
direction
of type
PlaybackDirection
, defaulting to
"normal"
The
playback direction
of the
animation effect
which defines whether playback
proceeds forwards, backwards, or alternates on each iteration.
easing
of type
DOMString
, defaulting to
"linear"
The
easing function
used to scale the time
to produce easing effects.
The syntax of the string is defined
by the

production
[CSS-EASING-1]
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:
If the
iterationStart
member of
input
exists
and is less than zero,
throw
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.
If the
iterations
member of
input
exists
and is less than zero or is the value
NaN
throw
TypeError
and abort this procedure.
If the
duration
member of
input
exists
and is less than zero or is the value
NaN
throw
TypeError
and abort this procedure.
If the
easing
member of
input
exists
but cannot be parsed using the

production
[CSS-EASING-1]
throw
TypeError
and abort this procedure.
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
};
endTime
of type
unrestricted double
The
end time
of the
animation effect
expressed in milliseconds since zero
local time
(that is, since the associated
animation
’s
start time
if this
animation effect
is
associated with an animation
).
This corresponds to
the end of the
animation effect
’s
active interval
plus any
end delay
activeDuration
of type
unrestricted double
The
active duration
of this
animation effect
localTime
of type
double
, nullable
The
local time
of this
animation effect
This will be
null
if this
animation effect
is not
associated with an animation
progress
of type
double
, nullable
The current
iteration progress
of this
animation effect
currentIteration
of type
unrestricted double
, nullable
The
current iteration index
beginning with zero for the first iteration.
In most cases this will be a (positive) integer.
However, for a zero-duration animation
that repeats infinite times,
the value will be positive
Infinity
As with
unresolved
times,
an unresolved
iteration index
is represented
by a
null
value.
6.6.
The
KeyframeEffect
interface
Keyframe effects
are represented by
the
KeyframeEffect
interface.
Exposed
Window
interface
KeyframeEffect
AnimationEffect
constructor
Element
target
object
keyframes
optional
unrestricted
double
or
KeyframeEffectOptions
options
= {});
constructor
KeyframeEffect
source
);
attribute
Element
target
attribute
CSSOMString
pseudoElement
attribute
CompositeOperation
composite
sequence
object
getKeyframes
();
undefined
setKeyframes
object
keyframes
);
};
Tests
effect-in-removed-iframe-crash.html
(live test)
(source)
KeyframeEffect (
target
keyframes
options
Creates a new
KeyframeEffect
object using the following procedure:
Create a new
KeyframeEffect
object,
effect
Set the
target element
of
effect
to
target
Set the
target pseudo-selector
to the result
corresponding to the first matching condition below:
If
options
is a
KeyframeEffectOptions
object
with a
pseudoElement
property,
Set the
target pseudo-selector
to the value of
the
pseudoElement
property.
When assigning this property,
the error-handling defined for
the
pseudoElement
setter on the interface
is applied.
If the setter requires an exception to be thrown,
this procedure must throw the same exception
and abort all further steps.
Otherwise,
Set the
target pseudo-selector
to
null
Let
timing input
be the result
corresponding to the first matching condition below:
If
options
is a
KeyframeEffectOptions
object,
Let
timing input
be
options
Otherwise (if
options
is a
double
),
Let
timing input
be a new
EffectTiming
object
with all members set to their default values
and
duration
set to
options
Call the procedure to
update the timing properties of an animation effect
of
effect
from
timing input
If that procedure causes an exception to be thrown,
propagate the exception and abort this procedure.
If
options
is a
KeyframeEffectOptions
object,
assign the
composite
property of
effect
to the corresponding value from
options
When assigning this property,
the error-handling defined for
the corresponding setter on the
KeyframeEffect
interface
is applied.
If the setter requires an exception to be thrown
for the value specified by
options
this procedure must
throw
the same exception
and abort all further steps.
Initialize the set of
keyframes
by performing the procedure
defined for
setKeyframes()
passing
keyframes
as the input.
Element
? target
The
target element
This may be
null
for animations that do not target a specific element.
object? keyframes
The set of
keyframes
to use.
The format and processing of this argument
is defined in
§ 6.6.3 Processing a keyframes argument
optional
KeyframeEffectOptions
options
Either a number specifying the
iteration duration
of the effect,
or a collection of properties specifying
the timing and behavior of the effect.
Examples of the usage of this constructor are given in
§ 6.6.1 Creating a new KeyframeEffect object
KeyframeEffect (source)
Creates a new
KeyframeEffect
object
with the same properties as
source
using the following procedure:
Create a new
KeyframeEffect
object,
effect
Set the following properties of
effect
using the corresponding values of
source
effect target
keyframes
composite operation
and
all specified timing properties:
start delay
end delay
fill mode
iteration start
iteration count
iteration duration
playback direction
and
easing function
Note:
Unlike
the
KeyframeEffect(target, keyframes, options)
constructor,
we do not need to re-throw exceptions
since the timing properties specified on
source
can be assumed to be valid.
KeyframeEffect
source
The
keyframe effect
from which to copy the properties
that define the new
keyframe effect
target
of type
Element
, nullable
The
target element
being animated by this object
(either the
effect target
if it is an
Element
or its
originating element
if it is a pseudo-element).
This may be
null
for animations
that do not target a specific element
such as an animation that produces a sound using an audio API.
pseudoElement
of type
CSSOMString
, nullable
The
target pseudo-selector
null
if this effect has no
effect target
or if the
effect target
is an element (i.e. not a pseudo-element).
When the
effect target
is a pseudo-element,
this specifies the pseudo-element selector (e.g.
::before
).
On setting,
sets the
target pseudo-selector
of the
animation effect
to the result of
pseudo-element parsing
on the provided value,
defined as the following:
Given the value
value
, perform the following steps:
If
value
is not
null
and is an
invalid

Throw
DOMException
with error name "
SyntaxError
".
Abort.
Note:
In effect, this means that if the result of this algorithm is
used to set a variable, then that variable remains unchanged.
Note:
Invalid in this context follows the definition of
an
invalid selector
defined in
[SELECTORS-4]
such that syntactically invalid pseudo-elements
as well as pseudo-elements for which the user agent
has no usable level of support
are both deemed invalid.
If
value
is one of the legacy Selectors Level 2 single-colon selectors
(':before', ':after', ':first-letter', or ':first-line'), then
return the equivalent two-colon selector (e.g. '::before').
Otherwise, return
value
composite
of type
CompositeOperation
The
composite operation
used
to composite this
keyframe effect
with the
effect stack
as specified by one of the
CompositeOperation
enumeration values.
On setting,
sets the
composite operation
property of this
animation effect
to the provided value.
sequence