[css-animations-2] [web-animations-2] Animation trigger event #12314

szager-chromium · 2025-06-10T22:20:31Z

Specification for event-based animation triggers, as discused in issue##12029

…-chromium/csswg-drafts into animation-trigger-event

…tion-trigger-event

szager-chromium · 2025-06-10T22:21:02Z

DavMila · 2025-06-11T12:03:50Z

css-animations-2/Overview.bs

@@ -770,6 +770,8 @@ for an [=animation trigger=] that enters its [=animation trigger/active interval

 The behavior of each value is defined in [[web-animations-2#trigger-behaviors]].

+Issue: Should 'animation-trigger-behavior' allow multiple values (currently it does)?


Hm, I don't think it does?

The '#' in the syntax description from line 734 means it accepts a comma-separated list of behaviors.

Oh I think that has to do with the fact that multiple animations can be specified in a comma-separated list. Each animation will then be mapped 1:1 with a comma-separated list of triggers. Each trigger still only gets one behavior. Though idk if this has been incorrectly represented in the spec text.

Yes, what @DavMila said is correct. I think this is called a coordinated list.

Got it; I will update the PR...

DavMila · 2025-06-11T12:04:21Z

web-animations-2/Overview.bs

+
+  <dt>''animation-trigger-type/repeat''</dt>
+  <dd>First, if [=play state=] is [=play state/running=] or [=play state/paused=]
+      perform the actions specified for the {{Animation/cancel}} function.


More of an FYI comment perhaps: I don't yet know if this is going to be different for event-based triggers but for scroll-triggered what we want isn't cancel() but more of a "reset"... which is not yet a concept defined in the web animations spec. Essentially, it does

animation.currentTime = 0; animation.pause();

Since you follow up by playing the animation, maybe this doesn't matter so much, but for CSS animations, cancel() will be accompanied by an animationcancel event which we might not want.

It's an interesting question about whether it's desirable to issue events for these transitions. They are not otherwise directly observable; is that a good thing? bad thing? Indifferent?

web-animations-2/Overview.bs

DavMila · 2025-06-11T12:10:46Z

web-animations-2/Overview.bs


-An [=animation trigger=] |trigger|
+  <dt>''animation-trigger-type/alternate''</dt>
+  <dd>Perform the actions specified for the {{Animation/reverse}} function.</dd>


Will we reverse the animation on the first event? Is that intended?

Great point! I need to think about this.

I updated to specify that if play state is idle then the effect is play(), otherwise the effect is reverse().

ydaniv

@szager-chromium thanks for starting this, but I think we still have very active spec work on AnimationTriggers currently tracked in #12119 that may affect the current spec substantially.
I gave my comments, so far mostly things regarding the API and logic of the declarative syntax and the model of event-based triggering, before diving in to the rest.

ydaniv · 2025-06-13T08:28:34Z

web-animations-2/Overview.bs

+type of an animation trigger is deduced from its attributes: a
+timeline-based animation trigger will have a non-empty {{AnimationTrigger/timeline}}
+attribute, while an event-based animation trigger will have non-empty
+{{AnimationTrigger/eventTarget}} and {{AnimationTrigger/eventType}} attributes.


Although we allow 2 types of animations, time-based and progress-based, using the animation property, we don't deduce that based on empty properties. On the contrary, we have auto initial values for all properties that are not needed when you use that type or the other.
So, IMHO we can't really add more properties to the API and expect those to be empty, both technically and design-wise.

I'm not sure if your concern is with the WAAPI interface or the CSS syntax, but the attributes on a WAAPI object can be undef or null. Is it maybe the word empty that you object to?

In the rest of the WAAPI proposal I added safeguards to ensure that an instance of AnimationTrigger will conform to the requirement:

!(trigger.eventType ^ trigger.eventTarget) && (trigger.timeline ^ trigger.eventTarget))

... so the trigger type is detectable based on these attributes.

ydaniv · 2025-06-13T09:34:41Z

web-animations-2/Overview.bs

+When a [=animation trigger/qualifying event=] is dispatched, the associated
+animation's playback is modified as follows,
+based on the trigger's {{AnimationTrigger/behavior}}
+and the current [=play state=] of the animation:


I don't think it's correct to specify behaviors based on the type of the trigger. I think we should be specifying how each time handles its internal state and apply its specified behavior, rather than how the behavior acts.

Respectfully, I disagree. Events are fundamentally ephemeral occurences, and I think it's more intuitive to express event-based triggers in terms of taking an action in response to an event without introducing the complexity of additional state, most of which is internal and thus not directly detectable. Conceptually, event-based triggers are like event handlers.

ydaniv · 2025-06-13T09:35:36Z

web-animations-2/Overview.bs

+
+<dl>
+  <dt>''animation-trigger-type/once''</dt>
+  <dd>If [=play state=] is [=play state/finished=], do nothing.


This way it's not really a once behavior. It will re-play as long as it's not finished.

If the animation is idle, then this will play it.
If it's running, then this will have no effect.
If it's paused this will un-pause it.
If it's finished, we do nothing.

That's the intended behavior, is there something unintuitive?

ydaniv · 2025-06-13T09:46:16Z

web-animations-2/Overview.bs

+Changes to animation playback occur when the associated [=timeline=] transitions
+between inside and outside the [=animation attachment range|attachment range=].


This is not so accurate in spec technical terms. The timeline doesn't transition, rather its progress goes in and out of its active interval

I'm not sure I understand your objection. The spec specifies when the trigger state is updated, and at that time if it's detected that the new state will be different from the previous state, then that can be considered a "transition". It's maybe a synthetic concept, but it's rigorous in terms of the current spec.

On a related note: the existing spec needs some clarification over when the trigger behaviors are applied -- specifically, they should only be applied when a transition occurs.

For example, consider this description of `alternate':

"If state is primary and did trigger is true, the effect is to reverse the associated animation."

If this logic is applied on every animation update, then the animation would be reversed on every frame. The intention is clearly that this behavior should be applied only when a transition occurs, but the spec doesn't say that.

ydaniv · 2025-06-13T10:08:46Z

css-animations-2/Overview.bs


 <pre class='propdef'>
 Name: animation-trigger
-Value: <<single-animation-trigger>>#
+Value: auto | none | <<single-animation-trigger>>#


So far we intentionally didn't have a none nor auto values for the animation-trigger property, though this may change depending on what we resolve in #12119

Also, probably if we do allow auto/none they should be part of the <single-animation-trigger> def and be allowed per trigger defintion.

I misunderstood before how coordinated lists were being used; I will fix this.

ydaniv · 2025-06-13T10:20:35Z

css-animations-2/Overview.bs

@@ -984,7 +1038,9 @@ Animation Type: not animatable
 </pre>

 <pre class=prod>
-<dfn>&lt;single-animation-trigger></dfn> = <<single-animation-trigger-behavior>> || [ none | auto | [ [ <<dashed-ident>> | <<scroll()>> | <<view()>> ] [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]{0,4} ] ]
+<dfn>&lt;single-animation-trigger></dfn> = [ <<single-animation-trigger-behavior>> | [ <<single-trigger-event>> | <<single-timeline-trigger>> ] ] <<single-animation-trigger-behavior>>?


I'm not sure I follow the logic here. Perhaps you meant to allow auto and none as possible alternatives and that's what got the syntax confusing here?

Also me not understanding coordinated lists; will fix.

ydaniv · 2025-06-13T10:28:01Z

css-animations-2/Overview.bs

-<dfn>&lt;single-animation-trigger></dfn> = <<single-animation-trigger-behavior>> || [ none | auto | [ [ <<dashed-ident>> | <<scroll()>> | <<view()>> ] [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]{0,4} ] ]
+<dfn>&lt;single-animation-trigger></dfn> = [ <<single-animation-trigger-behavior>> | [ <<single-trigger-event>> | <<single-timeline-trigger>> ] ] <<single-animation-trigger-behavior>>?
+
+<dfn>&lt;single-timeline-trigger></dfn> = [ <<dashed-ident>> | <<scroll()>> | <<view()>> ] [ normal | <<length-percentage>> | <<timeline-range-name>> <<length-percentage>>? ]{0,4}


You changed the syntax of timeline here. timeline also accepts none and auto which you removed here.

Also coordinated lists; will fix.

ydaniv · 2025-06-13T10:38:25Z

css-animations-2/Overview.bs

@@ -962,18 +964,70 @@ The values of 'animation-trigger-exit-range-start' have the following meaning:
                        it defaults to 100%.
 </dl>

+## The 'animation-trigger-name' property ## {#animation-trigger-name}


If this property is not a longhand sub-property of animation-trigger then IMO it should not be named using the scheme of animation-trigger-*. IIUC you meant to define this property as the event source declaration, am I right?
In that case, this raises some questions:

Is that declaration tree scoped?

Is the name reused for all event types that are emitted from this target?

Does containment properties affect its scope?

Can we lift this scope, same as the timeline-scope property does?

Do names collide and override eachother? Or can they be used multiple times?

Will these names be ever used only for the purpose (and scope) of animations?

After discussion with @flackr and @DavMila, I think the plan is to use a scoping mechanism similar to anchor positioning -- specifically, there will be a trigger-scope property to apply tree scoping, but in the absense of any applicable trigger-scope the scope will be global. As with anchor positioning, containment will not affect scope.

The name is only used to specify the event target; the event type is specified via animation-trigger-event or the animation-trigger shorthand.

I will change the property to trigger-name, to avoid confusion with the properties that can be set via animation-trigger shorthand.

OK, I still think that the type should be part of the event declaration on the target.
Is there a specific reason you want to put the type on the animation target? IMHO, from design perspective this seems to belong on the event target.

ydaniv · 2025-06-13T10:42:04Z

css-animations-2/Overview.bs

+The 'animation-trigger-name' property associates an element with
+all elements having an 'animation-trigger-event' property with


I think it's not accurate to say we "associate elements". The event needs to be associated with a target, and the target here is an animation(s).

I don't quite follow you here, but I will point out firstly that the term "target" appears to be overloaded here. Because we're working with events, and "event target" is a very well-understood concept, I'm using the term "target" to refer to the event target and not the element that will animate.

There is definitely an "association" happening here:

#event-target { trigger-name: --my-trigger; } #some-other-event-target { trigger-name: --my-trigger; } #animatable { animation-trigger-name: --my-trigger; animation-trigger-event: click; } #some-other-animatable { animation-trigger-name: --my-trigger; animation-trigger-event: keydown; }

If a click is dispatched to either #event-target or #some-other-event-target, then #animatable will run its animations. If a keydown is disaptched to either #event-target or #some-other-event-target, #some-other-animatable will run its animations.

Is there some other term besides "association" that better describes the relationships between these elements?

Because we have 2 elements in play here, I was trying to use "source" for the event target, and "target" for the animated element, but let's stick with event target.
I understand the association, we definitely need that mechanism.
I'm saying we associate the event target with an animation, and not really with another element. The animation is associated with its own target, which can be nulled or changed.

ydaniv · 2025-06-13T10:46:52Z

css-animations-2/Overview.bs

+The 'animation-trigger-event' property is used to specify the criteria
+for [=qualifying events=] that cause an [=event-based animation trigger=]


Shouldn't this be the other way around? As in, the event source should declare the types that emit its name, and the event targets should register to the name alone?
This is normally how you would register an event. You add a handler per type, and then these handlers can publish the name to trigger behavior.

Can you give an example of the syntax you have in mind? It's not clear to me how to express the following using your suggestion:

#event-target { trigger-name: --my-trigger; } #some-other-event-target { trigger-name: --my-trigger; } #animatable { animation-trigger-name: --my-trigger; animation-trigger-event: click; } #some-other-animatable { animation-trigger-name: --my-trigger; animation-trigger-event: keydown; }

First of all, this example is rather confusing to me. Did you intentionally used an example with two identical names? Are they supposed to collide? Or to be aggregated?

So to simplify with 2 different names, I was thinking on something like:

#event-target { trigger-event: --my-trigger click; } #some-other-event-target { trigger-event: --my-other-trigger keydown; } #animatable { animation-trigger: repeat event(--my-other-trigger); } #some-other-animatable { animation-trigger: --my-other-trigger; }

szager-chromium added 11 commits May 29, 2025 14:14

[css-animations-2] Fix bikeshed errors

b14d0a8

[web-animations-2] Spec for event-based animation triggers

a00f16c

bikeshed previews

e3c4860

in progress

146b2be

Fix keyframe-block

45d4ec4

Merge branch 'css-animations-2-bikeshed' of https://github.com/szager…

61ebaf3

…-chromium/csswg-drafts into animation-trigger-event

in progress

fc36f37

Merge branch 'main' of https://github.com/w3c/csswg-drafts into anima…

b76c534

…tion-trigger-event

nominally complete

8b88211

Delete html output

f3652ba

fix whitespace

a26f516

DavMila reviewed Jun 11, 2025

View reviewed changes

web-animations-2/Overview.bs Show resolved Hide resolved

DavMila reviewed Jun 11, 2025

View reviewed changes

Fix behavior spec for "alternate"

b1a5920

ydaniv reviewed Jun 13, 2025

View reviewed changes

flackr mentioned this pull request Jun 13, 2025

[css-animations-2] Move scroll and event animation triggers to independent namespace #12336

Open

		@@ -770,6 +770,8 @@ for an [=animation trigger=] that enters its [=animation trigger/active interval

		The behavior of each value is defined in [[web-animations-2#trigger-behaviors]].

		Issue: Should 'animation-trigger-behavior' allow multiple values (currently it does)?

		Changes to animation playback occur when the associated [=timeline=] transitions
		between inside and outside the [=animation attachment range\|attachment range=].

		The 'animation-trigger-name' property associates an element with
		all elements having an 'animation-trigger-event' property with

		The 'animation-trigger-event' property is used to specify the criteria
		for [=qualifying events=] that cause an [=event-based animation trigger=]

[css-animations-2] [web-animations-2] Animation trigger event #12314

Are you sure you want to change the base?

[css-animations-2] [web-animations-2] Animation trigger event #12314

Uh oh!

Conversation

szager-chromium commented Jun 10, 2025

Uh oh!

szager-chromium commented Jun 10, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

szager Jun 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ydaniv left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

szager Jun 12, 2025 •

edited

Loading