Copyright © 2026 World Wide Web Consortium. W3C® liability, trademark and permissive document license rules apply.
Defines CSS properties and an API for creating mechanisms that affect animation playback, based on DOM events resulting from user interaction, or on entry/exit of ranges on animation timelines.
CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, etc.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 “animation-triggers” in the title, like this: “[animation-triggers] …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.
This specification defines mechanisms for
affecting an animation’s playback
based on various user interactions invoking a specified trigger.
By specifying a trigger for an animation, that animation
becomes a triggered animation, making its
playback start delayed until that trigger occurs.
These triggers can be certain Events defined in [DOM],
or timeline based, such as view progress timelines. [SCROLL-ANIMATIONS-1]
This module provides both an imperative API building on the Web Animations API as well as a declarative API building on CSS Animations. [CSS-ANIMATIONS-2] [WEB-ANIMATIONS-1]
Web Animations [WEB-ANIMATIONS-1] defines an abstract conceptual model for animations on the Web platform, with elements of the model including animations and timelines, and associated programming interfaces. This specification extends the Web Animations model by defining triggered animation and allowing to perform playback control functions on them using triggers.
This specification introduces both programming interfaces for interacting with these concepts, as well as CSS properties that apply these concepts to CSS Animations [CSS-ANIMATIONS-2]. To the extent the behavior of these CSS properties is described in terms of the programming interfaces, User Agents that do not support scripting may still conform to this specification by implementing the CSS features to behave as if the underlying programming interfaces were in place.
This specification uses the timeline and ranges concept introduced in the Scroll-Driven Animations module [SCROLL-ANIMATIONS-1] for specifying progress-based timelines and animations.
Like most operations in CSS besides selector matching, features in this specification operate over the flattened element tree.
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.
While CSS animations are, by default, automatically run as soon as the appropriate animation values have been set on an element, the animation-trigger property allows the animation’s start to be delayed until an appropriate trigger occurs, and even paused, restarted, or reset by triggers (making it a triggered animation).
Currently, two types of triggers are defined:
timeline triggers, managed by the timeline-trigger properties, which allow animations to be triggered by entering or leaving certain timeline ranges. (Usually, view progress timelines, so an animation can be started when an element comes on-screen.)
event triggers, managed by the event-trigger properties, which allow animations to be triggered by certain user-interaction events, such as clicking an element or pressing certain keys.
A trigger is defined on some specific triggering element. All triggers have a trigger name, and the specific type of trigger dictates how and when it’s activated. A trigger can define multiple "types" of activation. (For example, timeline triggers can do different things on entry and exit.)
A trigger is used on potentially any element, creating a trigger instance on the element. (For example, animation-trigger associates a trigger instance with a specific animation on the element.) The trigger-using element specifies what actions to take when the trigger activates.
Note: This design for triggers and trigger instances, and the way they’re associated with triggered animations and <animation-action>s, is intentionally somewhat generic, intended to support using triggers for other purposes in the future. For now, though, triggered animations are the only user of this feature.
If a single element attempts to define multiple triggers of different types with the same trigger name, it only exposes one of the triggers, with event triggers winning over timeline triggers.
Note: This order is completely arbitrary (based on alphabetic order of the concept name), as this is just an error case.
Trigger names are global by default, usable by other elements regardless of their position. (Though they are tree-scoped names, so have interactions with shadow roots). If multiple elements define triggers with the same trigger name, the trigger defined by the later element in tree order is used.
The trigger-scope property can limit the scope of a name to a subtree of the document, so elements outside won’t see the chosen trigger name, and elements inside will only see the version of the trigger name defined inside the scope.
This property scopes trigger names to the subtree of the matching element. Its values are:
none No changes in trigger name scope. all Specifies that all trigger names defined by this element or its descendants—whose scope is not already limited by a descendant using trigger-scope—to be in scope only for this element’s flat tree descendants; and limits descendants to only match trigger names to triggers within this subtree.This value only affects trigger names in the same tree scope, as if it were a strictly matched tree-scoped name. (That is, trigger-scope: all acts identically to trigger-scope: --foo, --bar, ..., listing all relevant trigger names.)
<dashed-ident> Specifies that a matching trigger name defined by this element or its descendants—whose scope is not already limited by a descendant using trigger-scope—to be in scope only for this element’s flat tree descendants; and limits descendants to only match these trigger names to triggers within this subtree.The <dashed-ident> represents a strictly matched tree-scoped name, i.e. it can only match against trigger names in the same shadow tree.[CSS-SCOPING-1]
A timeline trigger is a trigger which is activated when some timeline enters the trigger’s activation range, or leaves the trigger’s active range. It is defined on an element with the timeline-trigger shorthand property, or its longhands.
A timeline trigger has a binary trigger state associated with it; it is initially "inactive". While it’s "inactive", the associated timeline entering (or starting in) the trigger’s activation range performs an associated entry action and switches the trigger state to "active"; while it’s "active", the associated timeline leaving the trigger’s active range performs an associated exit action and switches the trigger state to "inactive".
Note: By default, the active range is the same as the activation range; even when manually specified, the active range is always a superset of the activation range. The two ranges allow, for example, an animation-trigger to start an animation when an element is scrolled close to the center of the screen (using a view progress timeline with a relatively small window as the activation range), but not stop it until the element is fully off-screen (using cover as the active range).
A timeline trigger can have one or two actions associated with it when used as a trigger on an element (such as by animation-trigger). If two are specified, the first is the trigger’s entry action and the second is the trigger’s exit action; if only one is specified, the first is the trigger’s entry action and its exit action is to do nothing.
An element can define multiple timeline triggers, using the same timeline (potentially with different ranges) or different ones. The set of timeline-trigger longhands form a coordinating list property group, with timeline-trigger-name as the coordinating list base property, and each item in the coordinated value list defining the properties of a single timeline trigger.
If none is specified, the element does not define any timeline triggers.
If the same <dashed-ident> appears multiple times in the list, only the last one defines a timeline trigger; the preceding ones have no effect.
The timeline-trigger-source property specifies the timeline trigger’s associated timeline. Values have the same meaning as those of animation-timeline, except that none instead causes the corresponding entry in the coordinated value list to not define a timeline trigger.
The timeline-trigger-activation-range property is a shorthand property that sets timeline-trigger-activation-range-start and timeline-trigger-activation-range-end together in a single declaration. It has the same syntax as the animation-range property.
The behavior of timeline-trigger-activation-range is defined in Web Animations 2 § 3.6.5 Animation Trigger Ranges.
The timeline-trigger-activation-range-start and timeline-trigger-activation-range-end properties specify the timeline trigger’s associated activation range. Values have the same meaning as animation-range-start and animation-range-end.
The timeline-trigger-active-range property is a shorthand property that sets timeline-trigger-active-range-start and timeline-trigger-active-range-end together in a single declaration. It has the same syntax as the animation-range property.
The behavior of timeline-trigger-active-range is defined in Web Animations 2 § 3.6.5 Animation Trigger Ranges.
The timeline-trigger-active-range-start and timeline-trigger-active-range-end properties specify the timeline trigger’s associated active range. Values have the same meaning as animation-range-start and animation-range-end, with the following addition:
autoThe start (for timeline-trigger-active-range-start) or end (for timeline-trigger-active-range-end) is equal to the start/end of the timeline trigger’s activation range.
The timeline-trigger shorthand property sets all of timeline-trigger-name, timeline-trigger-source, timeline-trigger-activation-range, and optionally timeline-trigger-active-range at once.
A value of none is equivalent to none none normal.
Note: Due to significant potential ambiguities in the syntax (timeline-trigger-name vs timeline names in timeline-trigger-source; activation ranges vs active ranges), this shorthand’s values must be given in the specified order, rather than being settable in any order as is more common.
An event trigger is a trigger
which is activated when certain Events are fired at the element.
It is defined on an element with the event-trigger shorthand property,
or its longhands.
An event trigger can be defined as either stateless or stateful:
If stateless, it has a single set of enter events that activate it.
If stateful, it has two sets of events, its enter events and another set of exit events.
Event triggers are activated when one of its associated Events are fired on the page
with the trigger-defining element as its target.
If it’s stateful,
it has a binary trigger state associated with it,
initially "inactive":
while "inactive", it only activates when the defining element receives one of its enter events,
performing an associated enter action
and switching its trigger state to "active";
while "active", it only deactivates when it receives one of its exit events,
performing an associated exit action
and switching its trigger state back to "inactive".
A stateless event trigger must be given exactly one action for its trigger instance. A stateful one can be given one or two: the first is its enter action, and the second, if provided, is its exit action; if the second is not provided, the exit action is to do nothing.
Note: A stateful and stateless event trigger act differently even if you only assign a single action; a single-action stateful event trigger will effectively "turn off" until it receives one of its exit events, ignoring any of the enter events after the first, while a stateless one will repeatedly trigger for every enter event.
An element can define multiple event triggers,
using the same Events or different ones.
The set of event-trigger longhands
form a coordinating list property group,
with event-trigger-name as the coordinating list base property,
and each item in the coordinated value list
defining the properties of a single event trigger.
The proposal I drew this text from specified that it only cares if the element is the target of the event. We probably want to allow for bubbling and/or capturing, possibly as an opt in/out.
If none is specified, the element does not define any event triggers.
If the same <dashed-ident> appears multiple times in the list, only the last one defines an event trigger; the preceding ones have no effect.
The event-trigger-source property specifies what event or events activate the event trigger. Its values are:
noneThe corresponding entry in the coordinated value list does not define a trigger.
<event-trigger-event>+ [ / <event-trigger-event>+ ]?Defines what event(s) the event trigger responds to.
If a / is used in the value, the event trigger is stateful; the set of events before the / are the event trigger’s enter events, while those after the / are the exit events. (The same events can occur in both sets.)
Otherwise, the event trigger is stateless, and the provided events are its enter events.
<event-trigger-event> = activate | interest | click | touch | dblclick | keypress(<string>) | ...
Figure out the full set of events we want to handle.
The event-trigger shorthand property sets both event-trigger-name and event-trigger-source at once.
A value of none is equivalent to none none.
The animation-trigger property specifies whether the animation is a triggered animation, and if it is, what trigger it responds to and what actions it takes in response. animation-trigger is a reset-only sub-property of the animation shorthand. Its values are:
noneThe corresponding animation is not a triggered animation.
[ <dashed-ident> <animation-action>+ ]+The corresponding animation is a triggered animation, responding to the triggers named by each <dashed-ident>, and responding by taking the action named by the corresponding <animation-action>. (See § 2.1 Trigger Name Scoping: the trigger-scope property for how <dashed-ident>s are resolved to triggers.)
How many <animation-action>s a trigger accepts, and what exactly activates them, is determined by the type of the trigger. (Event triggers take one and possibly an optional second, depending on whether they’re stateless or stateful; timeline triggers take one and optionally a second.) Specifying the wrong number of actions (too many or too few) is valid syntactically, but causes the trigger to have no effect.
If multiple triggers occur simultaneously, they take effect in the order specified.
If the same <dashed-ident> is specified multiple times, all but the last have no effect.
The possible <animation-action> values, and what effect they have in each animation state:
play()
play()
play()
play()
play()
play()
play()
play()
play()
play()
play()
pause()
pause()
pause()
pause()
play()
play()
play()
There are no known privacy impacts of the features in this specification.
There are no known security impacts of the features in this specification.
Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.
All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]
Examples in this specification are introduced with the words “for example”
or are set apart from the normative text with class="example",
like this:
Informative notes begin with the word “Note” and are set apart from the
normative text with class="note", like this:
Note, this is an informative note.
Advisements are normative sections styled to evoke special attention and are
set apart from other normative text with <strong class="advisement">, like
this:
UAs MUST provide an accessible alternative.
Tests relating to the content of this specification may be documented in “Tests” blocks like this one. Any such block is non-normative.
Conformance to this specification is defined for three conformance classes:
style sheet A CSS style sheet. renderer A UA that interprets the semantics of a style sheet and renders documents that use them. authoring tool A UA that writes a style sheet.A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.
A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)
An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.
So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported component values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.
To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.
Once a specification reaches the Candidate Recommendation stage, non-experimental implementations are possible, and implementors should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec.
To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.
Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.