Title: CSS Animations Level 1
Status: WD
Work Status: Refining
Prepare for TR: yes
Date: 2023-03-02
Shortname: css-animations
Level: 1
Group: csswg
TR: https://www.w3.org/TR/css-animations-1/
ED: https://drafts.csswg.org/css-animations/
Previous Version: https://www.w3.org/TR/2018/WD-css-animations-1-20181011/
Previous Version: https://www.w3.org/TR/2017/WD-css-animations-1-20171130/
Previous Version: https://www.w3.org/TR/2013/WD-css3-animations-20130219/
Previous Version: https://www.w3.org/TR/2012/WD-css3-animations-20120403/
Editor: Dean Jackson, Apple Inc., dino@apple.com, w3cid 42080
Editor: L. David Baron, Google https://www.google.com/, https://dbaron.org/, w3cid 15393
Editor: Tab Atkins Jr., Google, http://xanthir.com/contact/, w3cid 42199
Editor: Brian Birtles, Invited Expert, brian@birchill.co.jp, w3cid 43194
Former Editor: David Hyatt, Apple Inc.
Former Editor: Chris Marrin, Apple Inc.
Former Editor: Sylvain Galineau, Adobe, galineau@adobe.com
!Issues List: https://github.com/w3c/csswg-drafts/labels/css-animations-1
Abstract: This CSS module describes a way for authors to animate the values of CSS properties over time, using keyframes. The behavior of these keyframe animations can be controlled by specifying their duration, number of repeats, and repeating behavior.
Link Defaults: css-values-3 (type)
url: https://dom.spec.whatwg.org/#constructing-events; type: dfn; text: event constructor;
urlPrefix: https://html.spec.whatwg.org/multipage/webappapis.html; type: dfn; spec: html
text: event handlers
text: event handler event type
text: event handler content attributes
text: event handler IDL attributes
urlPrefix: https://html.spec.whatwg.org/multipage/infrastructure.html; type: dfn; spec: html
text: HTML elements
spec:cssom-1; type:interface; text:CSSRule
Introduction
This section is not normative
CSS Transitions [[CSS3-TRANSITIONS]] provide a way to interpolate
CSS property values when they change as a result of underlying
property changes. This provides an easy way to do simple animation,
but the start and end states of the animation are controlled by the
existing property values, and transitions provide little control to
the author on how the animation progresses.
This proposal introduces defined animations, in which the author can
specify the changes in CSS properties over time as a set of keyframes.
Animations are similar to transitions in that they change the
presentational value of CSS properties over time. The principal difference
is that while transitions trigger implicitly when property values change,
animations are explicitly executed when the animation properties are applied.
Because of this, animations require explicit values for the properties
being animated. These values are specified using animation keyframes,
described below.
Many aspects of the animation can be controlled, including how many times
the animation iterates, whether or not it alternates between the begin and
end values, and whether or not the animation should be running or paused.
An animation can also delay its start time.
Value Definitions
This specification follows the CSS property definition conventions from [[!CSS2]]
using the value definition syntax from [[!CSS-VALUES-3]].
Value types not defined in this specification are defined in CSS Values & Units [[!CSS-VALUES-3]].
Combination with other CSS modules may expand the definitions of these value types.
In addition to the property-specific values listed in their definitions,
all properties defined in this specification
also accept the CSS-wide keywords as their property value.
For readability they have not been repeated explicitly.
CSS Animations Model
CSS Animations affect computed property values. This effect happens by
adding a specified value to the CSS cascade ([[!CSS3CASCADE]]) (at the
level for CSS Animations) that will produce the correct computed value
for the current state of the animation. As defined in [[!CSS3CASCADE]],
animations override all normal rules, but are overridden by !important
rules.
If at some point in time there are multiple animations specifying behavior
for the same property, the animation which occurs last in the value
of 'animation-name' will override the other animations at that point.
An animation does not affect the computed value before the application of the
animation (that is, when the 'animation-name' property is set on an element)
or after it is removed. Furthermore, typically an animation does not affect
the computed value before the animation delay has expired or after the end of
the animation, but may do so depending on the 'animation-fill-mode' property.
While running, the animation computes the value of those properties
it animates. Other values may take precedence over the animated value
according to the CSS cascade ([[!CSS3CASCADE]]).
While an animation is applied but has not finished, or has finished but has
an 'animation-fill-mode' of ''forwards'' or ''both'', the user agent must act
as if the 'will-change' property ([[!css-will-change-1]]) on the element
additionally includes all the properties animated by the animation.
The start time of an animation is the time at which the style applying
the animation and the corresponding @keyframes rule are both resolved.
If an animation is specified for an element but the corresponding
@keyframes rule does not yet exist, the animation cannot start; the
animation will start from the beginning as soon as a matching @keyframes
rule can be resolved. An animation specified by dynamically modifying the
element's style will start when this style is resolved; that may be
immediately in the case of a pseudo style rule such as hover, or may be
when the scripting engine returns control to the browser (in the case of
style applied by script). Note that dynamically updating keyframe style
rules does not start or re-start an animation.
An animation applies to an element if its name appears as one of the
identifiers in the computed value of the 'animation-name' property and the
animation uses a valid @keyframes rule. Once an
animation has started it continues until it ends or the 'animation-name' is
removed. Changes to the values of animation properties while the animation
is running apply as if the animation had those values from when it
began. For example, shortening the 'animation-delay' may cause the animation
to jump forwards or even finish immediately and dispatch an
{{animationend}} event.
Conversely, extending the 'animation-delay' may cause an animation to
re-start and dispatch an {{animationstart}} event.
The same @keyframes rule name may be repeated within an 'animation-name'.
Changes to the 'animation-name' update existing animations by iterating over
the new list of animations from last to first, and, for each animation,
finding the last matching animation in the list of existing
animations.
If a match is found, the existing animation is updated using the animation
properties corresponding to its position in the new list of animations,
whilst maintaining its current playback time as described above.
The matching animation is removed from the existing list of animations such
that it will not match twice.
If a match is not found, a new animation is created.
As a result, updating 'animation-name' from ‘a’ to
‘a, a’ will cause the existing animation for ‘a’ to
become the second animation in the list and a new animation will be
created for the first item in the list.
div {
animation-name: diagonal-slide;
animation-duration: 5s;
animation-iteration-count: 10;
}
@keyframes diagonal-slide {
from {
left: 0;
top: 0;
}
to {
left: 100px;
top: 100px;
}
}
This will produce an animation that moves an element from (0, 0) to
(100px, 100px) over five seconds and repeats itself nine times
(for a total of ten iterations).
Setting the 'display' property to ''display/none'' will terminate any running animation applied
to the element and its descendants. If an element has a 'display' of ''display/none'', updating
'display' to a value other than ''display/none'' will start all animations applied to the element
by the 'animation-name' property, as well as all animations applied to descendants
with 'display' other than ''display/none''.
While authors can use animations to create dynamically changing content, dynamically
changing content can lead to seizures in some users. For information on how to avoid
content that can lead to seizures, see Guideline 2.3: Seizures: Do not design content
in a way that is known to cause seizures ([[!WCAG20]]).
Implementations may ignore animations when the rendering medium is not interactive e.g. when printed.
A future version of this specification may define how to render animations for these media.
Declaring Keyframes
Keyframes are used to specify the values for the animating properties at various points
during the animation. The keyframes specify the behavior of one cycle of the animation;
the animation may iterate zero or more times.
Keyframes are specified using the @keyframes at-rule,
defined as follows:
The <> inside of ''@keyframes'' can only contain <> rules.
The <> inside of <> accepts any CSS property
except those defined in this specification,
but does accept the 'animation-timing-function' property
and interprets it specially.
None of the properties interact with the cascade
(so using ''!important'' on them is invalid and will cause the property to be ignored).
A ''@keyframes'' block has a name given by the <> or <> in its prelude.
The two syntaxes are equivalent in functionality;
the name is the value of the ident or string.
As normal for <>s and <>s,
the names are fully case-sensitive;
two names are equal only if they are codepoint-by-codepoint equal.
The <> additionally excludes the ''animation-name/none'' keyword.
For example, the following two ''@keyframes'' rules have the same name,
so the first will be ignored:
The <> for a <> consists of a comma-separated list of percentage values or the keywords ''from'' or ''to''. The selector is used to specify the percentage along the duration of the animation that the keyframe represents. The keyframe itself is specified by the block of property values declared on the selector. The keyword ''from'' is equivalent to the value ''0%''. The keyword ''to'' is equivalent to the value ''100%''.
Values less than ''0%'' or higher than ''100%'' are invalid
and cause their <> to be ignored.
Note: Note that the percentage unit specifier must be used on percentage values. Therefore, ''0'' is an invalid keyframe selector.
If a ''0%'' or ''from'' keyframe is not specified, then the user agent constructs a ''0%'' keyframe
using the computed values of the properties being animated. If a ''100%'' or ''to'' keyframe is not
specified, then the user agent constructs a ''100%'' keyframe using the computed values of the
properties being animated.
The <> contains properties and values. The properties
defined by this specification are ignored in these rules, with the exception of
'animation-timing-function', the behavior of which is described below. In addition, properties qualified with !important are invalid and ignored.
If multiple ''@keyframes'' rules are defined with the same name,
the last one in document order wins,
and all preceding ones are ignored.