In CSS, what does animation-timeline: scroll() do to an animation, and how does that differ from the default document timeline?

## Two kinds of timeline Every CSS animation is attached to a *timeline*, and the timeline is what supplies the animation's progress. The default is `animation-timeline: auto`, meaning the **document timeline** — a clock that starts when the page loads and advances in real time. That is why `animation-duration` is expressed in seconds: the animation asks the clock how much time has passed and maps it onto the keyframes. A **scroll progress timeline** replaces that clock with a scroll position. It has no seconds at all. It has a *scrollable range* — everything between fully scrolled to the start and fully scrolled to the end — and it reports where inside that range the container currently sits, as a progress value from 0% to 100%. ## What scroll() names `scroll()` creates an *anonymous* scroll progress timeline, meaning it is defined inline on the animated element rather than given a name. Its syntax is `scroll(<scroller> <axis>)`, both parts optional: - **scroller** — `nearest` (the default: the nearest ancestor that is actually a scroll container), `root` (the viewport's scrolling element), or `self` (this element, if it is itself a scroll container). - **axis** — `block` (the default), `inline`, `x`, or `y`. So `scroll(root block)` is "how far down the page are we", and `scroll(self inline)` is "how far along its own horizontal scroll is this carousel". ```css @keyframes grow-bar { from { transform: scaleX(0); } to { transform: scaleX(1); } } #progress { transform-origin: left center; animation: grow-bar linear; animation-timeline: scroll(root block); } ``` ## Duration, easing, and range Leave `animation-duration` unset. Its `auto` behaviour on a progress timeline is "cover the whole timeline", which is almost always what you want; a time value there does not mean seconds of scrolling and is a classic source of an animation that appears finished before you have scrolled anywhere. To animate over only part of the scroll, use `animation-range` rather than a duration. The other animation longhands still apply, they just operate over progress instead of time. `animation-timing-function` eases the mapping from scroll progress to keyframe progress — which is why `linear` is the usual choice here, since any other curve makes the element appear to lag or race the user's finger. `animation-fill-mode` still controls what happens outside the active range, and `animation-iteration-count` above 1 makes the keyframes repeat within the scroll range. ## Scrubbing, not playing The biggest conceptual shift is that the animation is not *played*, it is *scrubbed*. Progress is a pure function of scroll position: scroll down and it advances, scroll up and it rewinds, stop and it freezes mid-way. Nothing queues, nothing catches up, and there is no notion of the animation being "late". This is also why the feature is a signal question. The JavaScript equivalent meant attaching a scroll listener, reading a scroll offset, and writing styles — work that lands on the main thread on every frame and stutters under load. Declared in CSS, the browser owns the mapping and can run it off the main thread when the animated properties are ones it can composite, such as `transform` and `opacity`. ## Why it silently does nothing Scroll-driven animations fail quietly — no console error — so know the usual causes: - **The scroller has no scrollable overflow.** A timeline whose range is zero is inactive, and an animation on an inactive timeline never progresses. This is why a `nearest` timeline often works in a tall page and dies in a short one. - **`nearest` picked a scroller you did not mean.** Any ancestor with scrollable overflow claims it, not just the one you were thinking of. - **The `animation` shorthand reset it.** `animation` resets `animation-timeline` to its initial value, so a shorthand written *after* `animation-timeline` wipes it. Always put the shorthand first, or use only longhands. ## Support Chromium shipped scroll-driven animations in Chrome 115 (2023); Safari and Firefox added support afterwards, so verify the current baseline for your audience rather than assuming universal support. Because the whole feature degrades to "the animation simply does not run", it wraps cleanly in `@supports (animation-timeline: scroll())` as an enhancement over a static base style.