[css-animations-2] Add animation-trigger for triggering animations when an element is in a timeline's range

[ydaniv]

Entry animations are pretty common on the web. Currently in order to trigger time-based animations when an element enters the viewport we have to use IntersectionObserver.
The problems with this:

• requires writing some amount of JS for rather simple use-case
• requires waiting for JS to start for playing animations (may be slow when sites import a lot of JS)
• IntersectionObservers take transforms into account, so that messes up the ability to properly know when an element is in viewport when animating from outside of it using transforms
• the web engine is not aware of the fact that the element will be animated on entry and may punish you on perf

The idea of using an in-view selector was dismissed, so another idea is perhaps to extend the animation-play-state property to support a sort of "trigger" values instead of only running/paused, and reuse the new animation-range values syntax to toggle between these states, which could look like:

.element {
  animation-name: fly-in;
  animation-duration: 1s;
  animation-fill-mode: backwards;

  /* magic right here */
  animation-play-state: toggle(entry 50%);
}

A good thing about ranges is that they already ignore transforms for SDA, so the same semantics could apply here and help solve this problem of transforms messing with initial position for triggering on viewport intersection.

While this condition evaluates to false the value computes to paused, and when it's true it will change to running.

Another requirement would be to be able to both toggle every time the computed value changes, and also have it set once. Perhaps this could be inferred from the animation-fill-mode, so that both and backwards are used for those respectively. Or maybe use specific syntax for distinguishing between the two.

cc @bramus @flackr

[ydaniv]

also ping @birtles

[birtles]

The idea of using an in-view selector was dismissed

I'm just curious about what the discussion was here. I know in the very very early days of the scroll-driven animations spec we have scroll triggers which would have been awesome--basically like declarative intersection observer so you could trigger transitions or even just static changes. The main problem was just that you couldn't easily implement them such that they run on the compositor. I think they were probably the same thing as in-view selectors. Is that the reason the in-view selector was dismissed?

Perhaps this could be inferred from the animation-fill-mode, so that both and backwards are used for those respectively.

Fill modes are tricky. They don't compose very well and we had to introduce the whole effect replacing mechanism just to prevent them from leaking memory. At times we've talked about deprecating them if we could. They might be the right primitive here, but just as a knee-jerk reaction, I think it would be worth considering other options before we try to overload them for this.

[ydaniv]

Is that the reason the in-view selector was dismissed?

There was a specific section on this in the CSSWG wiki but can't find it now cause the wiki is down ):
But essentially it said this would be problematic in cases where you could select based on this state, and then undo that state inside the same rule.

I should note that a sort of an in-view state is also being considered for state() queries, which may also be useful for other use-cases, like for having different elements for checking state and applying style change.

I know in the very very early days of the scroll-driven animations spec we have scroll triggers which would have been awesome--basically like declarative intersection observer so you could trigger transitions or even just static changes

Yes, there was such issue (couldn't find it) but we agreed that "scroll-driven" is technically and conceptually different from "scroll-trigger". So we closed that one.
Having a declarative intersection observer would be great, but since it was stuck I'm trying here to find a way forward and also addressing specific cases for triggering animations.

I think it would be worth considering other options before we try to overload them for this

Understood, they may be completely orthogonal to this case, just trying to consider sensible defaults.

[bramus]

Yehonatan and I discussed this IRL while both at CSS Day. Must say I like the general idea of using animation-play-state for this:

• It hints at “this is a regular animation, but it’ll only play from a certain point (in space)”
• It correctly assumes to not be a timeline – so doesn’t fit into animation-timeline – because the animation would still run on the document timeline.
• It doesn’t require a parent container or anything
• animation-duration will still have its meaning

Good remark by Brian on not overloading animation-fill-mode for this. Perhaps the “trigger once” thing could be a flag in the triggering function.

As for bikeshedding: I would name the function trigger() instead of toggle().

FWIW: an alternative idea I had in the back of my mind somewhere was to adjust animation-duration to accept something like trigger(5s, entry 10%) but that seems more convoluted than Yehonatan’s proposal.

[ydaniv]

Giving this more thought, using animation-range will not work here since it specifies every point on the range for a continuous event, and what we need here is actually a singular trigger, more like an IntersectionObserver.
Instead of knowing the exact point on the range in each frame we need to resolve a boolean value indicating whether the element is intersecting the viewport or not.

This can be interpreted as 2 possible options:

1. toggle between running/paused as the value changes - sort of play/pause
2. trigger a single change to running when the value resolves to true - sort of play/stop, with 2 scenarios:
   a. run once
   b. re-run every time the value is true

IMO option 1. is less common, and will only have a meaning for long/infinite animations, and it's probably much more interesting to pursue option 2 with both variations.

Naming aside, syntax could possibly looks something like:

For 2.a.:

.element {
  animation-play-state: trigger(in-view 50%, once);
}

or for 2.b.:

.element {
  animation-play-state: trigger(in-view 50%);
}

And possibly with rootMargins, if we follow IntersectionObserver's options:

.element {
  animation-play-state: trigger(in-view 50% / 10% 0);
}

Also assuming root isn't specifiable for now and defaulting to nearest, which is nearest scroll-container, same for ViewTimelines.

[flackr]

In the early days when we discussed this, we recognized that this was not complicated to enable for animations, but we were concerned about how developers could use this to start transitions as it seemed like a natural thing people would want to do. There was a proposal to have a media query style syntax in #4339. See also #7478. e.g.

@scroll-trigger(>500) {
  /* style rules to trigger animation or transition */
}

The issue with this is that evaluating this change requires a global style recalculation and as such would be unlikely to be able to be started on the compositor. I'm happy to solve this for animations which if we set up up-front we could dynamically trigger from the compositor. We should think about whether there are any ways we could set this up for transitions as well. E.g. maybe for transitions we could do something similar to @starting-style but associate it with a particular trigger point. Then to composite the transition this style information and the trigger would be passed along to the compositor.

I don't think it's a good idea to re-use animation-play-state for this as you don't want the animation to pause if you scroll past the trigger point and then back before it. Instead you want one of two behaviors:

• Play to completion, or
• If the animation would trigger in reverse at this scroll threshold, start reversing the animation.

My thinking around this is that it is somewhat similar to animation-delay but repeatable. I'd propose introducing something like an animation-trigger property which would have values for the various modes you may want this to work. The trigger could be a point on an animation timeline which could be time-based or could be scroll based. This might be something like the following:

.element {
  animation-trigger: trigger(view(), entry 100%) once;
}

In general the property might look something like:

animation-trigger: <animation-trigger-timeline
    <normal | <length-percentage> | <timeline-range-name> <length-percentage>>?
    <once | repeat | alternate>>#

The initial value would match the current behavior that animations "trigger" once when they are defined.

[ydaniv]

@flackr

We should think about whether there are any ways we could set this up for transitions as well. E.g. maybe for transitions we could do something similar to @starting-style but associate it with a particular trigger point. Then to composite the transition this style information and the trigger would be passed along to the compositor.

Transitions, unlike animations, can't use the trigger in a property/value since they are triggered by the cascade itself. Having excluded the option for having a trigger as a selector, I think the only option still being discussed now is using state queries for that in #6402. I think that direction may also prove useful for the more advanced use-case for animations, when you want to separate the triggering element from the animated element.

I don't think it's a good idea to re-use animation-play-state for this as you don't want the animation to pause if you scroll past the trigger point and then back before it. Instead you want one of two behaviors:

• Play to completion, or
• If the animation would trigger in reverse at this scroll threshold, start reversing the animation.

Yes, these 2 options sound option 2 I mentioned above.

The main problem I see with introducing a new property and not extending animation-play-state is how will they interact with each other? What does having a trigger and having a play-state of either running or paused mean?
Will paused mean "ignore the trigger and stay paused"? And running is "play when defined or when triggered"?

trigger could be a point on an animation timeline which could be time-based or could be scroll based

I'm not sure we need the a point on a timeline. The time-based one is simply a delay, right? And the scroll-based one may be confusing, because what you probably want is a simply intersection, no matter which direction or point on the view-timeline the element is at. E.g: what happens with view(), entry 100% if the page was navigated to in mid-scroll and then user scrolled to reveal the element from the scrollport's start edge? Does it really matter?

I guess if we add something like view(), in 100% and view(), out 100% we could cover all cases.

<once | repeat | alternate>

I really like this part! Kind of binds together all the use-cases (:

[flackr]

Yes, these 2 options sound option 2 I mentioned above.

My apologies, I missed that this was the behavior you proposed for it. I still worry this isn't well described by the paused animation-play-state as it suggests option 1 based on what changing play state to paused usually does. Also when you haven't triggered the animation yet I think it should be in the before phase (as if you had a delay you haven't hit yet), rather than paused at the start and should probably hold the after phase after it finishes. This lets the developer decide whether it should fill or not.

The main problem I see with introducing a new property and not extending animation-play-state is how will they interact with each other? What does having a trigger and having a play-state of either running or paused mean? Will paused mean "ignore the trigger and stay paused"? And running is "play when defined or when triggered"?

If you think of this as similar to animation-delay, the animation is just "running" the whole time but it's in the before phase until triggered (i.e. only producing an effect if you have fill: backwards). If you set it to paused the animation would I suppose start paused when the trigger is passed holding the first keyframe until you unpause it.

I'm not sure we need the a point on a timeline. The time-based one is simply a delay, right?

When given a document timeline yes. I was thinking in the long run you might pass it a point on a (yet to be defined) video timeline or other such time-based triggers which are not simple delays.

And the scroll-based one may be confusing, because what you probably want is a simply intersection, no matter which direction or point on the view-timeline the element is at. E.g: what happens with view(), entry 100% if the page was navigated to in mid-scroll and then user scrolled to reveal the element from the scrollport's start edge? Does it really matter?

There are a few ways that a single point could be interpreted.

• Whenever you go from one side of the given point to the other you trigger the animation.
• Whenever you have a "time" >= the trigger point, trigger the animation.
• Whenever you pass the trigger point in a particular direction, trigger the animation.

We could imply all of these options from the proposed once | repeat | alternate. E.g. alternate implies the animation happens every time you cross in the direction you crossed in, and maybe the other two can decide which direction they care about - or maybe they care about the direction determined by the animation-direction?

It sounds like you're suggesting though that you might want an upper limit, such as trigger a particular animation anytime you scroll between 500px and 1000px (such that a particular element is intersecting the viewport). I think in order to avoid timing issues you'd probably want to trigger even if the user scrolled past the range without ever entering it just so that you'd be in a consistent state regardless of scroll speed. I'm a bit worried this could get into an arbitrarily complex syntax space for multiple triggers, repeating triggers etc, however maybe a range based trigger always plays forward when you enter the range and plays backwards when you leave it and if you don't want one of the directional trigger points it is conceptually infinite / the start or end of the range.

[ydaniv]

I still worry this isn't well described by the paused animation-play-state as it suggests option 1 based on what changing play state to paused usually does. Also when you haven't triggered the animation yet I think it should be in the before phase (as if you had a delay you haven't hit yet), rather than paused at the start and should probably hold the after phase after it finishes. This lets the developer decide whether it should fill or not

Yes, it should hold the fill state until triggered and after finishing, so I guess in that sense it's not really the play-state according to the model, and rather a new thing that toggles phases, as you say.

If you think of this as similar to animation-delay, the animation is just "running" the whole time but it's in the before phase until triggered (i.e. only producing an effect if you have fill: backwards). If you set it to paused the animation would I suppose start paused when the trigger is passed holding the first keyframe until you unpause it.

Yep, that sounds good.

I was thinking in the long run you might pass it a point on a (yet to be defined) video timeline or other such time-based triggers which are not simple delays.

Hmm, yes, +1 on that.

It sounds like you're suggesting though that you might want an upper limit, such as trigger a particular animation anytime you scroll between 500px and 1000px (such that a particular element is intersecting the viewport).

Yeah, sort of, you helped realize what I actually wanted is a range in which the computed value is a boolean, rather than progress. So inside it it's true and false outside. And a single toggle-point can be simply from range start to infinity. And these cover well scroll/view/hover/time/etc.

or maybe they care about the direction determined by the animation-direction?

I think that defines the initial direction.

I'm a bit worried this could get into an arbitrarily complex syntax space for multiple triggers, repeating triggers etc

We may probably want to add multiple triggers, but I'd be happy to solve the single case first (:

[ydaniv]

@flackr there is a problem with repeat, as it creates a non-continuous point on the timeline's edges.

For example take an element with view() entry 50% exit 50% repeat, and the user is scrolling just beyond one of the 50% points, where the trigger value is flipped back to false, and that should reset the animation back to before phase. Or maybe just if stopping just beyond the 50% point and then scrolling back into the range it should reset back and trigger again.

Either way we get a visual jump.
I think it's something that needs a proper handling OOTB. Only thing I can think of now is allowing multiple triggers, and then the author can add another negated (false inside the range) trigger for reset.
WDYT?

[ydaniv]

I think another way to tackle this is by imagining how this would be implemented today:

You'd have 2 IntersectionObservers: one for triggering on entry (isIntersecting=true) that flips the value to true, and a second one for triggering on exit (isIntersecting=false), with a range that has to be larger than the first one's, that flips the value to false.

So you end up with 2 ranges:

1. range for entry to flip to true
2. range for exit to flip to false

Then, it could become something along the line of:

animation-trigger: view(block 15%) cover / view(block -10%) cover repeat;

And the second range is optional of course, and has to be larger than the first range (I think that's possible to validate, right?).

[ydaniv]

Also, @flackr , could you please change the tagging to css-animations-2? I don't have these permissions, thanks!

[bramus]

You'd have 2 IntersectionObservers: one for triggering on entry (isIntersecting=true) that flips the value to true, and a second one for triggering on exit (isIntersecting=false), with a range that has to be larger than the first one's, that flips the value to false.

I think this is a separate use case here, where you can trigger-in on entry and trigger-out on exit. The initial use-case was to trigger-in and having an option to run the animation only once.

[ydaniv]

@bramus, yes, once is probably the default value and first use-case we should start with.
alternate is interesting, and perhaps rather easy to add.
repeat introduces the discontinuity on the edges of the range, so is a bit of a problem.

[ydaniv]

@bramus, @flackr, would appreciate your thoughts on what's suggested so far. Perhaps we can wrap up something that can be presented on the agenda for TPAC?

Currently what we have is the following:

Syntax:

animation-trigger: <animation-trigger-timeline
    <normal | <length-percentage> | <timeline-range-name> <length-percentage>>?
    <once | repeat | alternate>>#

With once and alternate being more easy to define.
While repeat is a bit more tricky since it has a discontinuity point.

---

It would be nice if we could squeeze in a solution for repeat, current suggestion is to have a syntax with optionally 2 ranges/timelines: first for when switching from false to true, and a second one, that replaces the first once the value is true, for when switching from true back to false, in order to solve the discontinuity issue.
Also, perhaps the could be a restriction on the second range/timeline to make it >= then the first one.

[ydaniv]

ping @mirisuzanne

[flackr]

To clarify what I suggested earlier, I think it would be helpful to always have a range (i.e. start and end) for all cases. When the end of the range is not specified it could be some form of infinity / auto value so that most of the time developers would only need to specify a start point.

Then, it becomes easier to rationalize all of the behaviors. The "trigger" occurs whenever a rendering update results in going from outside of the range to inside of the range or vice versa, and the behavior depends on the mode:

• once will play the animation a single time when you enter the range. Subsequent entry / exiting is ignored.
• repeat will play the animation every time you enter the range.
• alternate will play the animation forward every time you enter the range and reverse the animation every time you exit the range.

@ydaniv does having a trigger range not fix the discontinuity issue?

[bramus]

@flackr I’m a bit confused about the proposed range. When I think of a Scroll-Trigger Animation, I think of a certain line that the elements needs to cross, not a range. Say I want to trigger an animation when scrolling past the 1000px scroll offset, would your range then be [1000px, +Infinity] to indicate that the animation can play while in that range?

About the repeat value: Wouldn’t that have weird visual results when scrolling down and up again? Take a trigger line at a scroll offset of 1000px with a fade-in animation:

1. When scrolling up and crossing that offset, the element fades in and – most likely – stays in its end state of opacity: 1.
2. When then scrolling back down again the element remains as it was, thus at opacity: 1.
3. When then scrolling back up and crossing the line, the animation will restart. This would mean that the element has opacity: 1 when at the 999px scrolll offset, and then jumps back to the animation (which starts at opacity: 0) when at the 1000px scroll offset. This feels like a glitch.

[ydaniv]

@flackr

To clarify #8942., I think it would be helpful to always have a range (i.e. start and end) for all cases. When the end of the range is not specified it could be some form of infinity / auto value so that most of the time developers would only need to specify a start point.

Yes, of course. If you don't expect navigation to an anchor then you're fine with just the start.

does having a trigger range not fix the discontinuity issue?

Usually "entrance" animations are usually "from" animations, meaning, they animate to an implicit to keyframe or an identity transform, etc. So your range needs to account for the element to be visible. Question is, what happens when exiting the range on the same position where the element is visible?
Perhaps we could say there's no change when exiting, but then if you enter again the animation will go back to 0% and play again, just like @bramus described above ☝️ .
My intent was to see if we can allow specifying the exit point a bit further, where the element is out of view, so that a nicer effect can be easily achieved.

@bramus

When I think of a Scroll-Trigger Animation, I think of a certain line that the elements needs to cross, not a range. Say I want to trigger an animation when scrolling past the 1000px scroll offset, would your range then be [1000px, +Infinity] to indicate that the animation can play while in that range?

It's just like scroll vs. view timelines again (: You can set s specific point on the scroll and that's a valid use-case. But usually you'll set a trigger using IntersectionObserver and wait for an intersection, which can better described by view timeline. And the nice extra is that this also fixes the awkwardness of transforms on the same element, that by ignoring them we can reason about the trigger point without worrying about the initial animation frame.

[kizu]

When I think of a Scroll-Trigger Animation, I think of a certain line that the elements needs to cross, not a range. Say I want to trigger an animation when scrolling past the 1000px scroll offset, would your range then be [1000px, +Infinity] to indicate that the animation can play while in that range?

I can imagine use-cases where we'd want to completely skip an animation when jumping over the range, for example if we have a long page with multiple scroll-triggered animations, and are landing over some sections via an #anchor. In some of these cases you could expect the animation to play when scrolling back up to its range.

Even more, I can imagine the cases for the “range” being very short, like half a screen high, meaning that we'd only want to trigger an animation when we're in the range, for example if we have some kind of “screen” where we'd want to play some animation when that screen is completely in the viewport. Scrolling from either top or bottom, we'd want to trigger the animation only when the screen is completely in the viewport.

[ydaniv]

I can imagine use-cases where we'd want to completely skip an animation when jumping over the range, for example if we have a long page with multiple scroll-triggered animations, and are landing over some sections via an #anchor

This can be achieved with what @flackr said above, without a range end the animation will be triggered above, not skipped though. But with once behavior the element will already be animated.

ven more, I can imagine the cases for the “range” being very short, like half a screen high, meaning that we'd only want to trigger an animation when we're in the range, for example if we have some kind of “screen” where we'd want to play some animation when that screen is completely in the viewport. Scrolling from either top or bottom, we'd want to trigger the animation only when the screen is completely in the viewport.

IIUC this should be covered using view() or at least referencing another named view-timeline.

[flackr]

Usually "entrance" animations are usually "from" animations, meaning, they animate to an implicit to keyframe or an identity transform, etc. So your range needs to account for the element to be visible. Question is, what happens when exiting the range on the same position where the element is visible? Perhaps we could say there's no change when exiting, but then if you enter again the animation will go back to 0% and play again, just like @bramus described above ☝️ . My intent was to see if we can allow specifying the exit point a bit further, where the element is out of view, so that a nicer effect can be easily achieved.

I think I understand now, you want a point before which you can safely restore the before state without it being visible to the user. E.g. to put it in concrete terms maybe the start trigger is on entry 100% but the exit trigger would be at entry 0% (where the element isn't visible).

[flackr]

I made a crude polyfill of this at https://flackr.github.io/web-demos/scroll-triggered/scroll-triggered.js . I'm hoping this can be helpful in putting together concrete demos.

Demo using it: https://flackr.github.io/web-demos/scroll-triggered/

[cdoublev]

Is it intentional not to allow auto for animation-trigger-exit-range in animation-trigger?

For example, animation-trigger: --timeline 0% 90% auto 100%. Sorry if this example does not make sense, I have not yet grasped all of these new features.

[ydaniv]

@cdoublev I think it's an overlook. I probably added the auto values after I wrote the syntax for animation-trigger.

[cdoublev]

One thing I noticed while fiddling with the current grammar is that authors cannot use --timeline normal 100% to declare normal for the default range and 100% for the exit range. They must use --timeline normal normal 100%.

Perhaps / could be used as a range separator?

(added some productions for better readability)

<single-animation-trigger> =
     <single-animation-trigger-type>
  || [ 
         none 
       | auto 
       | <timeline-ident> <animation-range-value>{1,2} [ / <animation-exit-range-value>{1,2} ]? 
     ]

<animation-range-value> = normal | <length-percentage> | <timeline-range-name> <length-percentage>?
<animation-exit-range-value> = auto | <animation-range-value>
<timeline-ident> = <dashed-ident> | <scroll()> | <view()>

[ydaniv]

One thing I noticed while fiddling with the current grammar is that authors cannot use --timeline normal 100% to declare normal for the default range and 100% for the exit range. They must use --timeline normal normal 100%.

Perhaps / could be used as a range separator?

Yes! I noticed too.
I think it's reasonable but didn't get formal response to this suggestion.

I think we also have an issue of auto both as timeline and exit-range values. Need to define how these are resolved as well. So either another possible usage for / or perhaps make auto for exit-range unspecifiable? Or something else?

But then again, if you have timeline set to auto then ranges are ignored. And I see you covered that with your syntax suggestion, clever!