[FEE-11100] Scroll-driven Animations
INFO
Animate elements based on scroll position (progress bars, parallax, fade-ins), entirely in CSS, with zero JavaScript. Where the browser runs the animation off the main thread, a busy main thread does not stall it; see "Why CSS-native wins" for which browsers that covers.
Baseline: Limited availability
Supported in Chrome 115+ and Edge 115+. Safari added support in Safari 26 (September 2025); threaded, off-main-thread execution arrived in Safari 26.4. Firefox still ships the feature behind layout.css.scroll-driven-animations.enabled in stable as of Firefox 152 (June 2026). It is on by default in Nightly and is a named Interop 2026 priority. Verify current Firefox status on MDN before targeting it in production.
Context
Scroll-linked effects have always been a staple of modern UIs: reading-progress bars at the top of articles, elements that fade in as they enter the viewport, sticky headers that change style as the page scrolls. Every one of these has historically required JavaScript.
The classic pattern is a scroll event listener feeding requestAnimationFrame:
window.addEventListener('scroll', () => {
requestAnimationFrame(() => {
const progress = window.scrollY / (document.body.scrollHeight - window.innerHeight);
progressBar.style.transform = `scaleX(${progress})`;
});
});This approach has a fundamental flaw: scroll events fire on the main thread. If a long JavaScript task is running (parsing a script, handling a React re-render, processing a large dataset), the scroll handler is delayed. The user scrolls, and the progress bar does not move until the task finishes.
IntersectionObserver improved the enter/exit case (it detects when an element crosses the viewport boundary), but it cannot express progress-based animation. An element is either intersecting or it is not; there is no "30% into the viewport" callback.
Third-party libraries filled the gap. GSAP ScrollTrigger and Locomotive Scroll offer polished, reliable scroll animation APIs. They apply requestAnimationFrame loops and will-change hints to minimize jank, but they still run on the main thread and add kilobytes to every page that uses them.
CSS Scroll-driven Animations replaces this pattern. The animation-timeline property drives an animation's progress from scroll position instead of a JavaScript event, using the same keyframe system that already handles transform and opacity animations. Whether that removes main-thread jank depends on the browser; see "Why CSS-native wins" in Design Thinking for which engines run it off the main thread.
A concrete case: a long-form article page needs a reading-progress bar that fills as the reader scrolls from top to bottom, plus a series of cards that fade in as each one enters the viewport. Built the classic way, that is two scroll listeners and two requestAnimationFrame loops, each needing its own cleanup. With CSS Scroll-driven Animations, both effects are declared entirely in CSS; the Example section below shows both.
Visual
Scroll-driven animations bind to a scroll position through one of two mechanisms: an anonymous timeline that references the nearest scroll container, or a named timeline that any permitted element can reference.
| Anonymous | Named | |
|---|---|---|
| Syntax | scroll() / view() | scroll-timeline-name + animation-timeline: --name |
| Scroll container | Nearest scrollable ancestor (or root) | Any named container; descendants only, unless a common ancestor sets timeline-scope |
| Use case | Single element animating with its own ancestor's scroll | Coordinating multiple elements, including non-descendants, with one scroll region |
| Code overhead | Minimal | A declaration on the container, a reference on the animated element, and timeline-scope if the element is not a descendant |
For most scroll-linked effects, anonymous timelines are shorter and clearer. Reach for named timelines when the animated element is not a descendant of the scroll container, or when multiple unrelated elements need to animate in sync with the same scroll region.
Example
Both examples are wrapped in a single @media (prefers-reduced-motion: no-preference) block, as required.
Example 1: Reading progress bar using scroll()
<div class="progress-bar"></div>
<article class="content">
<!-- long article content -->
</article>.progress-bar {
position: fixed;
top: 0;
left: 0;
width: 100%;
height: 4px;
background: #e2e8f0;
z-index: 100;
transform-origin: left;
}
@media (prefers-reduced-motion: no-preference) {
@keyframes grow-progress {
from { transform: scaleX(0); }
to { transform: scaleX(1); }
}
.progress-bar {
animation: grow-progress linear;
animation-timeline: scroll(root block);
/* root = document root scroll container, block = vertical axis */
}
}scroll(root block) links the animation to the root scroll container (the document) on its block (vertical) axis. As the user scrolls from the very top to the very bottom of the page, grow-progress runs from scaleX(0) to scaleX(1), filling the bar.
Omitting the arguments (just scroll()) uses the nearest scrollable ancestor and the block axis. For a full-page progress indicator, always specify root explicitly so the correct scroll container is used regardless of DOM nesting.
Example 2: Cards that fade in using view()
<section class="cards">
<div class="card">Card One</div>
<div class="card">Card Two</div>
<div class="card">Card Three</div>
</section>.card {
/* Base state before animation plays */
opacity: 1;
transform: translateY(0);
background: #fff;
padding: 2rem;
margin-block-end: 2rem;
border-radius: 8px;
box-shadow: 0 2px 8px rgb(0 0 0 / 0.1);
}
@media (prefers-reduced-motion: no-preference) {
@keyframes fade-up {
from {
opacity: 0;
transform: translateY(40px);
}
to {
opacity: 1;
transform: translateY(0);
}
}
.card {
animation: fade-up ease-out both;
animation-timeline: view();
/* Play the animation over the first 40% of the element's entry phase */
animation-range: entry 0% entry 40%;
}
}view() links the animation to the element's own visibility inside its scroll container. animation-range: entry 0% entry 40% tells the browser: play the full fade-up keyframe sequence from the moment the element starts entering the viewport until it has entered 40% of the way. The both fill mode (via the animation shorthand) holds opacity: 0 before entry and opacity: 1 after.
Best Practices
- MUST wrap all scroll-driven animation rules in
@media (prefers-reduced-motion: no-preference). Scroll-driven animations that move elements, change opacity, or alter layout can trigger vestibular disorders in sensitive users. This wrapper is not optional. - SHOULD animate only
transformandopacityinside scroll-driven keyframes. These properties are compositor-eligible: they do not trigger layout or paint, and they run entirely on the compositor thread. - MUST NOT animate
top,left,width,height,margin,padding, or any property that triggers layout recalculation. Doing so forces the browser to run layout on every scroll tick, negating the performance benefit of moving to CSS. - SHOULD use
animation-timeline: view()for "animate as element enters viewport" effects. - SHOULD use
animation-timeline: scroll()for page-wide progress indicators (reading bars, parallax backgrounds). - SHOULD test with
@supports (animation-timeline: view())for progressive enhancement if the feature is critical to layout rather than pure decoration. - SHOULD set
animation-fill-mode: bothwhen usingview()timelines to hold the final keyframe state after the element leaves view.
Design Thinking
Why JS scroll listeners cause jank
JavaScript event handlers, including scroll, are dispatched on the browser's main thread. The main thread is also responsible for parsing HTML and JavaScript, running framework code, handling user input, and executing timers. On a busy page, the main thread can be occupied for tens or hundreds of milliseconds at a time.
When a scroll event fires while the main thread is busy, it queues behind whatever is already running. By the time the handler executes, the user has scrolled further, and the animation jumps to catch up. requestAnimationFrame reduces this by batching updates to the next paint, but it still waits for the main thread.
How GSAP ScrollTrigger addressed it
GSAP ScrollTrigger wraps scroll listeners in a requestAnimationFrame loop and adds will-change: transform hints to elements that will animate. This tells the browser to promote those elements to their own compositor layers, allowing the GPU to handle their transforms. The result is significantly smoother than naive scroll listeners, but the triggering logic (the part that decides what the current progress is and what CSS to apply) still executes on the main thread.
Why CSS-native wins
CSS Scroll-driven Animations does not run JavaScript during scrolling. In Chrome, Edge, and Safari 26.4+, the browser registers the relationship between a scroll container and an animation at parse time. During scrolling, the compositor thread reads the scroll position and advances the animation directly, without notifying the main thread. The compositor thread already handles all composited transform and opacity updates.
On those engines:
- A JavaScript task that blocks the main thread for 200 ms does not stall the animation; it keeps advancing at the correct scroll position throughout the block.
- You write no JavaScript, so there is no
requestAnimationFrameloop to tear down on unmount and nothing that can leak a scroll listener. - The feature degrades silently: browsers that do not support
animation-timelinesimply show the element at its default state, treating the@keyframesas if they were never applied.
Safari shipped scroll-driven animations in Safari 26 (September 2025) but ran them on the main thread until Safari 26.4 added threaded execution. On Safari 26.0-26.3 you still get the zero-JavaScript benefit, but a busy main thread can still stall the animation the same way it would a JavaScript scroll listener. Only Chrome, Edge, and Safari 26.4+ deliver both zero-JS authoring and off-main-thread smoothness.
Deep Dive
Named scroll timelines
The anonymous scroll() and view() functions work when the animated element is a descendant of the scroll container. When the element is not a descendant (for example, a fixed sidebar that needs to animate in sync with a specific scroll region), use a named timeline together with timeline-scope:
/* On a common ancestor of both .scroll-region and .sidebar-indicator */
body {
timeline-scope: --region-timeline;
}
/* On the scroll container */
.scroll-region {
scroll-timeline-name: --region-timeline;
scroll-timeline-axis: block;
/* Shorthand: scroll-timeline: --region-timeline block; */
overflow-y: scroll;
}
/* On the non-descendant element that wants to animate with that container's scroll */
.sidebar-indicator {
animation: track-scroll linear both;
animation-timeline: --region-timeline;
}
@keyframes track-scroll {
from { transform: scaleY(0); }
to { transform: scaleY(1); }
}The scroll-timeline-name property declares the container as a named scroll timeline source, but by default that name is visible only to descendants of the declaring element. .sidebar-indicator above is not nested inside .scroll-region, so without timeline-scope its animation-timeline: --region-timeline reference would resolve to nothing and the element would not animate. Setting timeline-scope: --region-timeline on body, a common ancestor of both elements, extends the name's visibility to that ancestor and everything inside it, which is what makes the reference work.
The @scroll-timeline at-rule (historical)
Early drafts of the specification used an @scroll-timeline at-rule to declare named timelines. This syntax was present in very early Chromium prototypes (pre-Chrome 115) and in documentation from 2021–2022. It was replaced before the feature reached stable release by the scroll-timeline-name and scroll-timeline-axis properties. If you encounter @scroll-timeline in an older tutorial or library, treat it as obsolete: it is not implemented in any current browser and is not part of the current specification.
animation-fill-mode: both and view timelines
When using view(), an element's animation has a defined start and end point within the scroll timeline. After the element fully exits the view, the animation is outside its active range. Without animation-fill-mode, the element reverts to its initial CSS state (which may mean re-appearing at opacity: 0 after it has scrolled past). Setting animation-fill-mode: both (or using both in the animation shorthand) retains the final keyframe values after the active range ends.
View timeline phases
The animation-range property accepts named phase keywords corresponding to geometric regions of the element's journey through the scroll container:
| Phase | Meaning |
|---|---|
entry | The element is partially visible and entering the viewport (leading edge has crossed the scroll port's far boundary, trailing edge has not yet crossed it) |
contain | The element is fully contained by the scroll port, both edges visible (applies when the element is shorter than the scroll port), or it fully covers the scroll port, no edges visible (applies when the element is taller than the scroll port, such as a tall hero section) |
exit | The element is partially visible and leaving the viewport |
cover | The full visibility arc: from the moment the element's leading edge first appears to the moment its trailing edge disappears |
Mixing phases is valid: animation-range: entry 50% exit 50% starts the animation at the midpoint of entry and ends at the midpoint of exit.
Progressive enhancement pattern
/* Default: no animation, element is in its final visible state */
.card {
opacity: 1;
transform: none;
}
/* Enhanced: animate on scroll where supported */
@supports (animation-timeline: view()) {
@media (prefers-reduced-motion: no-preference) {
.card {
animation: fade-up ease-out both;
animation-timeline: view();
animation-range: entry 0% entry 40%;
}
}
}Author the finished state as the default, then add the scroll animation inside @supports; unsupported browsers show the finished content with no animation rather than broken content. Setting the base state to opacity: 1 here means users on Firefox (where the feature is still flagged) or older browsers see all content normally.
Combining scroll() and view() on the same page
There is no conflict in using both types of timeline on the same page. A reading progress bar can use animation-timeline: scroll(root block) while individual cards use animation-timeline: view(). Each animated element independently references its own timeline source; they do not interfere with each other.
It is also valid to apply multiple animations to one element, each with a different timeline, as long as the animation-timeline list entries correspond 1:1 to the animation-name list entries:
.hero-image {
animation: fade-in ease-out both, parallax-shift linear both;
animation-timeline: view(), scroll(root block);
animation-range: entry 0% entry 60%, normal;
}Here fade-in uses the element's own view() timeline, while parallax-shift uses the root scroll progress. The animation-range: normal value for the second animation means the full scroll range from 0% to 100%.
Browser Support
| Browser | First version | Notes |
|---|---|---|
| Chrome | 115 | Full support: scroll(), view(), animation-range, named timelines |
| Edge | 115 | Chromium-based, same as Chrome |
| Safari | 26 | Shipped in Safari 26 (September 2025). Ran on the main thread until Safari 26.4, which added threaded, off-main-thread execution |
| Firefox | — | Behind layout.css.scroll-driven-animations.enabled in stable as of Firefox 152 (June 2026); on by default in Nightly and a named Interop 2026 priority |
Progressive enhancement check:
@supports (animation-timeline: view()) {
/* scroll-driven animation styles */
}Or in JavaScript:
const supported = CSS.supports('animation-timeline', 'view()');Because Firefox has not enabled this by default, production use should either treat scroll-driven animations as pure progressive enhancement (decorative, with a graceful fallback) or use the @supports guard with a JavaScript fallback for browsers that lack support.
Related Topics
- FEE-11101 @starting-style.
@starting-stylehandles element entry transitions on first render; scroll-driven animations handle progress through an ongoing scroll timeline. Combine both for a card that animates on its initial render and again on scroll-triggered entry. - FEE-11001 CSS Anchor Positioning. Both are newer CSS features that replace JavaScript-driven positioning and animation: CSS Anchor Positioning removes JS measurement, and scroll-driven animations remove JS scroll listeners.
References
- CSS scroll-driven animations — MDN Web Docs
- timeline-scope — MDN Web Docs
- Animate elements on scroll with Scroll-driven animations — Chrome for Developers
- A guide to Scroll-driven Animations with just CSS — WebKit Blog
- WebKit Features for Safari 26.4 — WebKit Blog
- Scroll-Driven Animations — Josh W. Comeau
- Scroll-driven Animations demos — scroll-driven-animations.style
- Interop 2026 — wpt.fyi
- CSS Scroll-Driven Animations Level 1 — W3C Editors' Draft