Skip to content

[web-animations-1][animation-triggers-1] Move AnimationTrigger details #14043

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
DavMila wants to merge 2 commits into
base: main
Choose a base branch
from
Open

[web-animations-1][animation-triggers-1] Move AnimationTrigger details #14043

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1efe456
Add a few missing closing tags
DavMila Jun 10, 2026
6e61c6d
[web-animations-1][animation-triggers-1] Move AnimationTrigger details
DavMila Jun 12, 2026
File filter

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
386 changes: 385 additions & 1 deletion animation-triggers-1/Overview.bs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,228 @@ urlPrefix: https://www.w3.org/TR/web-animations-1/; type: dfn
█▌ █▌ █▌ ████ ███▌ ███▌ █████▌ █▌ █▌ ███▌
-->

# Triggers # {#triggers}
# Animation Triggers # {#triggers}
-----------------

## Overview ## {#triggers-overview}

An <dfn export>animation trigger</dfn> is used to control the playback
of its associated [=animation=] for time-driven animations.
Like animations, [=animation triggers=] are associated with a [=timeline=]
and are attached to an [=animation attachment range|attachment range=].

Issue: Should there be any effect of triggers on scroll-driven animations?

## Animation Trigger Internal State ### {#trigger-state}

An [=animation trigger=] |trigger|
has an internal boolean <dfn export>did trigger</dfn> flag, which is initially false,
and an internal <dfn export lt="animation trigger state">state</dfn> with
these possible values:

<dl dfn-for="animation trigger state">
<dt><dfn>idle</dfn>
<dd>
The [=animation effect=] associated |animation| remains in
its [=animation effect/before phase=] and stays at zero [=animation/current time=].

<dt><dfn>primary</dfn>
<dd>
When switched to this value the [=animation trigger state/primary=] behavior type defined by |type| is applied to |animation|.

<dt><dfn>inverse</dfn>
<dd>
When switched to this value the [=animation trigger state/inverse=] behavior type defined by |type| is applied to |animation|.
</dl>

The values of [=animation trigger state|state=] and [=did trigger=] are
updated by the [=updating animation trigger state=] procedure, described below.

Issue: Do we need a formal resolution on the spec of the idle state?

## Animation Trigger Behavior ## {#trigger-behaviors}

An [=animation trigger=] has an associated <dfn export>animation trigger behavior</dfn>
which, along with [=did trigger=] and [=animation trigger state|state=],
determines the [=animation trigger|trigger=]'s effect on its
associated [=animation=]'s playback.

The [=animation effect=] associated with an [=animation trigger=]
in the [=animation trigger state/idle=] state
remains in its [=animation effect/before phase=] and
stays at zero [=animation/current time=],
regardless of the trigger's [=did trigger=] flag or [=animation trigger state|state=].
Otherwise, the effect on playback is as follows for
given values of <var ignore=''>behavior</var>:

<dl>
<dt>''animation-trigger-behavior/once''</dt>
<dd>
<dl class=switch>
: If [=animation trigger state|state=] is [=animation trigger state/primary=],
:: the effect is to [=play an animation|trigger=] the associated animation.

: Otherwise,
:: the trigger has no effect.
</dl>
</dd>

<dt>''animation-trigger-behavior/repeat''</dt>
<dd>
<dl class=switch>
: If [=animation trigger state|state=] is [=animation trigger state/primary=],
:: the effect is to [=play an animation|trigger=] the associated animation.

: If [=animation trigger state|state=] is [=animation trigger state/inverse=],
:: the effect is to reset the associated [=animation effect=] back to
its [=animation effect/before phase=] and its associated [=animation=]’s
[=animation/start time=] to zero.
</dl>
</dd>

<dt>''animation-trigger-behavior/alternate''
<dd>
<dl class=switch>
: If [=animation trigger state|state=] is [=animation trigger state/primary=]
and [=did trigger=] is false,
:: the effect is to [=play an animation|trigger=] the associated animation.

: If [=animation trigger state|state=] is [=animation trigger state/primary=]
and [=did trigger=] is true,
:: the effect is to [=reverse an animation|reverse=] the associated animation.

: If [=animation trigger state|state=] is [=animation trigger state/inverse=]
:: the effect is to [=reverse an animation|reverse=] the associated animation.
</dl>
</dd>

<dt>''animation-trigger-behavior/state''
<dd>
<dl class=switch>
: If [=animation trigger state|state=] is [=animation trigger state/primary=]
:: the effect is to [=play an animation|trigger or resume=] the associated animation.

: If [=animation trigger state|state=] is [=animation trigger state/inverse=]
:: the effect is to [=pause an animation|pause=] the associated animation.
</dl>
</dd>
</dl>

Issue: Do we need a proper definition for "behavior types primary/inverse"?

## Animation Trigger Active Interval ## {#trigger-active-interval}

Each [=animation trigger=] defines an <dfn for="animation trigger">active interval</dfn>
and only one such interval. This interval is the segment of the timeline’s progress
during which the trigger’s [=animation trigger state|state=] is set to [=animation trigger state/primary=].

## Animation Trigger Ranges ### {#trigger-ranges}

An [=animation trigger=] has two [=animation attachment range|ranges=],
the <dfn>default range</dfn> and the <dfn>exit range</dfn>.
The [=exit range=] is used to replace [=default range=] and extend
the [=animation trigger/active interval|active interval=].

Issue: Should we specify that that exit range’s edges can only be equal to or greater than the default range’s edges?

Depending on its most recent [=animation trigger state|state=] |state|, the
[=animation trigger/active interval|active interval=] is defined as follows:

<dl class=switch>
: If |state| is [=animation trigger state/primary=],
::
Then |interval| is set to [=exit range=].

: Otherwise,
::
|interval| is [=default range=].

</dl>

## Setting a Trigger of an Animation ## {#setting-animation-trigger}

<div algorithm="Setting a Trigger of an Animation">
The procedure of <dfn>setting a trigger of an animation</dfn> |animation|,
to |new trigger|, is as follows:

1. Let |old trigger| be the current [=animation trigger=] of |animation|, if any.

1. If |new trigger| is the same object as |old trigger|, abort this procedure.

1. Let the [=animation trigger|trigger=] of |animation| be |new trigger|.

1. Run the procedure to [=updating animation trigger state=] for |new trigger|.
</div>

## Setting the timeline of an Animation Trigger ## {#setting-trigger-timeline}

<div algorithm="setting timeline of animation trigger">
The procedure of <dfn>setting timeline of animation trigger</dfn> |trigger|,
to |new timeline| which may be <code>null</code>, is as follows:

1. Let |old timeline| be the current value of |trigger|.{{AnimationTrigger/timeline}}, if any.

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

1. Set |trigger|.{{AnimationTrigger/timeline}} to |new timeline|.

1. Run the [=updating animation trigger state=] procedure for |trigger|.
</div>

## Updating Animation Trigger State ## {#updating-trigger-state}

<div algorithm="updating animation trigger state">
The procedure of <dfn>updating animation trigger state</dfn>
of an [=animation trigger=] |trigger| is as follows:

1. Let |did trigger| be the current value of |trigger|'s [=did trigger=] flag.

1. Let |behavior| be |trigger|'s associated [=animation trigger behavior=].

1. Set |trigger|.[=animation trigger state|state=] as follows:
<dl class=switch>
: If |trigger|’s [=local time=] is [=unresolved=],
::
Then abort this procedure.

: Otherwise,
::

<dl class=switch>
: If |behavior| is ''animation-trigger-behavior/once'' and |did trigger| is true,
::
Then abort this procedure.

: Otherwise,
::

<dl class=switch>
: If |trigger| is inside its [=animation trigger/active interval|active interval=],
::
1. Set |trigger|.[=animation trigger state|state=] to [=animation trigger state/primary=].
1. Set |trigger|.[=did trigger=] to true.

: Otherwise,
::

<dl class=switch>
: If |did trigger| is true,
::
Set |trigger|.[=animation trigger state|state=] to [=animation trigger state/inverse=].

</dl>

</dl>

</dl>

</dl>

</div>

Issue: Should it be the correct/expected behavior for the "did trigger" flag to reset to false if the timeline becomes idle again?

## Triggers Declared By CSS ##

While CSS animations are, by default,
automatically run as soon as the appropriate 'animation' values have been set on an element,
Expand Down Expand Up @@ -628,6 +849,169 @@ urlPrefix: https://www.w3.org/TR/web-animations-1/; type: dfn
</caption>
</table>

<h2 id="programming-interface">Programming interface</h2>


<h3 id="the-animationtrigger-interface">The <code>AnimationTrigger</code> interface</h3>

<pre class='idl'>
[Exposed=Window]
interface AnimationTrigger {
constructor(optional AnimationTriggerOptions options = {});
attribute AnimationTimeline timeline;
attribute AnimationTriggerBehavior behavior;
attribute any rangeStart;
attribute any rangeEnd;
attribute any exitRangeStart;
attribute any exitRangeEnd;
};
</pre>

<wpt>
interfaces/TimelineTrigger/constructor.html
</wpt>

<div dfn-type=constructor class=constructors dfn-for="AnimationTrigger">
: <dfn lt="AnimationTrigger(options)">AnimationTrigger(|options|)</dfn>
::
Creates a new {{AnimationTrigger}} object using the following procedure:

1. Create a new {{AnimationTrigger}} object, |trigger|.

1. Set |trigger|.[=did trigger=] to false.

1. Set |trigger|.[=animation trigger state|state=] to [=animation trigger state/idle=].

1. Set |trigger|.{{AnimationTrigger/behavior}} to |options|.{{AnimationTriggerOptions/behavior}}.

1. Set [=default range=] of |trigger| using |options|.{{AnimationTriggerOptions/rangeStart}} and |options|.{{AnimationTriggerOptions/rangeEnd}},
following the same rules as the KeyframeAnimationOption
<a href="#dom-keyframeanimationoptions-rangestart">rangeStart</a> and
<a href="#dom-keyframeanimationoptions-rangeend">rangeEnd</a> respectively.

1. Set [=exit range=] of |trigger| using |options|.{{AnimationTriggerOptions/exitRangeStart}} and |options|.{{AnimationTriggerOptions/exitRangeEnd}},
following the same rules above for [=default range=], unless they are set to
"auto", in which case they are set to their corresponding side
of the [=default range=].

1. Run the procedure for [=setting timeline of animation trigger=]
on |trigger| passing |options|.{{AnimationTriggerOptions/timeline}} as the <var ignore>new timeline</var>.

<div dfn-type=argument class=parameters
dfn-for="AnimationTrigger/AnimationTrigger(options)">

: <dfn>options</dfn>
:: Configuration parameters for the newly-created trigger.

</div>

</div>

<div dfn-type=attribute class=attributes
dfn-for="AnimationTrigger">

: <dfn>timeline</dfn>
::
Returns the [=timeline=] for this trigger
or `null` if this timeline is [=inactive timeline|inactive=].

: <dfn>behavior</dfn>
::
Returns the [=animation trigger behavior|behavior=] of this trigger.

: <dfn>rangeStart</dfn>
::
Returns the [=default range=]’s start of this trigger.

: <dfn>rangeEnd</dfn>
::
Returns the [=default range=]’s end of this trigger.

: <dfn>exitRangeStart</dfn>
::
Returns the [=exit range=]’s start of this trigger.

: <dfn>exitRangeEnd</dfn>
::
Returns the [=exit range=]’s end of this trigger.

</div>

<h3 id="the-animationtriggeroptions-dictionary">The <code>AnimationTriggerOptions</code> dictionary</h3>

<pre class='idl'>
dictionary AnimationTriggerOptions {
AnimationTimeline? timeline;
AnimationTriggerBehavior? behavior = "once";
(TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeStart = "normal";
(TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) rangeEnd = "normal";
(TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) exitRangeStart = "auto";
(TimelineRangeOffset or CSSNumericValue or CSSKeywordValue or DOMString) exitRangeEnd = "auto";
};
</pre>

<div dfn-type=dict-member class=members
dfn-for="AnimationTriggerOptions">

: <dfn>timeline</dfn>
::
The timeline to which the trigger is associated.
If not specified, the trigger is associated with [=default document timeline=].

: <dfn>behavior</dfn>
::
The behavior of the trigger.
If not specified, the trigger's behavior is ''animation-trigger-type/once''.

: <dfn>rangeStart</dfn>
::
The start of the trigger’s [=default range=].
If not specified, the [=default range=]’s start is set to "normal".

: <dfn>rangeEnd</dfn>
::
The end of the trigger’s [=default range=].
If not specified, the [=default range=]’s end is set to "normal".

: <dfn>exitRangeStart</dfn>
::
The start of the trigger’s [=exit range=].
If not specified, the [=exit range=]’s start is set to "auto".

: <dfn>exitRangeEnd</dfn>
::
The end of the trigger’s [=exit range=].
If not specified, the [=exit range=]’s end is set to "auto".

</div>

<h3 id="the-animationtriggerbehavior-enumeration">The <code>AnimationTriggerBehavior</code> enumeration</h3>

<pre class='idl'>
enum AnimationTriggerBehavior { "once", "repeat", "alternate", "state" };
</pre>

<dl dfn-type=enum-value
dfn-for="AnimationTriggerBehavior">

: <dfn>once</dfn>
::
''animation-trigger-behavior/once''.

: <dfn>repeat</dfn>
::
''animation-trigger-behavior/repeat''.

: <dfn>alternate</dfn>
::
''animation-trigger-behavior/alternate''.

: <dfn>state</dfn>
::
''animation-trigger-behavior/state''.

</dl>

# Privacy Considerations # {#privacy-considerations}

There are no known privacy impacts of the features in this specification.
Expand Down
Loading