A partial archive of discourse.wicg.io as of Saturday February 24, 2024.

Scroll-linked animations


We’d like to propose a mechanism for web animations to be driven by scrolling instead of by time.

We have a draft proposal which provides two ways to accomplish this: via script (the ScrollTimeline interface), and via CSS (the animation-timeline property).

This proposal was inspired by Dean Jackson’s earlier proposal on www-style, and is substantially similar to the “timelines” portion of Google’s Generalized Animations proposal. We’d like to use this as a starting point for further work.

Triggering animations

An earlier version of our proposal also provided a mechanism for a regular time-driven animation to be triggered by scrolling past a certain scroll position (inspired by the animation-trigger property from Dean’s proposal, and similar to the “triggers” portion of Generalized Animations).

However, this part was dropped, because we realized that the types of web animations that web authors are most likely to want to trigger based on scrolling, are CSS transitions (as opposed to CSS animations), and we can’t trigger CSS transitions from the compositor (thus negating the main advantage of the proposal over triggering in an onscroll handler or requestAnimationFrame callback).

We’re still interested in doing something for triggers, but are not sure exactly what. Ideas are welcome!

Relationship with AnimationWorklet

This proposal has some overlap with AnimationWorklet.

Some use cases of AnimationWorklet, such as parallax and “hidey-bars”, can be expressed using a scroll-linked animation. For these cases, we believe it to be an advantage to express these declaratively, and using a mechanism that’s in some ways easier to implement.

Other use cases of AnimationWorklet, such as custom timing functions and animating scroll offsets, cannot be expressed using a scroll-linked animation, making AnimationWorklet still useful as an independent proposal.


In the 2.1.2. Navigation highlight effect use case, would the highlight change based on fixed scroll offsets in pixels (or percentages maybe)? If yes:

  • What happens if you don’t know beforehand at which point each section happens? Do you need to measure the position of each heading and use those as “stops” in the animation?
  • What happens if you measure the position of each heading and the layout changes after that, because a web font loaded or an image loaded or the user changed the font-size or some scripted elements toggled content visibility on/off?

A common use case we had (in my web agency) for scroll-based animations was not so much “animate relative to the scroll offset in this container”. This can happen sometimes, but not often. More common is: “update an animation and/or start another animation when this element appears in the viewport”. Currently, we use GSAP and ScrollMagic for that. This proposal seems to hint at this use case, but relying on fixed scroll values, which are brittle.


@fvsch, currently the spec only supports specifying scroll offsets as pixels or percentages. You are right to point out that this is inconvenient for some use cases.

We’re definitely open to adding support for element-relative offsets. (Dean’s original proposal contained an example that used a scroll(elements) syntax that seemed like it was intended to be element-relative, but I didn’t quite understand the intended semantics of that syntax. There was also an allusion to scroll snapping, which I also didn’t understand, possibly because the scroll snapping proposal has changed significantly since Dean’s post.)

Ideas about what element-relative offsets might look like are welcome!


Google is also interested in collaborating on a scroll linked animations proposal.


Great to hear that Google supports this moving forward.

I’m in contact with the folks proposing this spec. We will begin the process of transferring the existing repository to the WICG.