Scroll-driven animations let an animation's progress track a user's scroll position rather than a clock. Bramus Van Damme, who authored Chrome's documentation on the feature and maintains the ten-part YouTube course "Unleash the Power of Scroll-Driven Animations," covers both the mechanics and a set of practical demos. What follows are notes from that course.
What scroll-driven means
These are distinct from scroll-triggered animations. A triggered animation fires on scroll and then runs to completion on its own, much like an IntersectionObserver callback. A scroll-driven animation pauses, plays, and reverses in step with the scroll direction.
The learning curve is shallow: any existing CSS or WAAPI animation can be attached to scrolling, and attaching it is the only new concept to absorb. There is a performance argument as well. JavaScript libraries typically react to scroll events on the main thread, which blocks rendering and produces jank; this approach yields hardware-accelerated animations.
Support starts at Chrome 115, testable with @supports (animation-timeline: scroll()). Since feature detection on that property alone is no longer sufficient, Bramus has documented that animation-range must be checked too. As with any motion feature, honor prefers-reduced-motion.
Attaching an animation: scroll() and ScrollTimeline
Start from a conventional CSS animation.
@keyframes grow-progress {
from {
transform: scaleX(0);
}
to {
transform: scaleX(1);
}
}
#progress {
animation: grow-progress 2s linear forwards;
}
That definition scales an element from zero width to full width over two seconds with linear easing, holding only in the forwards direction. Adding animation-timeline rewires it to scroll progress:
animation-timelinenames the timeline driving the animation.scroll()builds an anonymous scroll timeline that tracks the nearest ancestor scroller in the block direction.
#progress {
animation: grow-progress 2s linear forwards;
animation-timeline: scroll();
}
With the link established, animation-duration is superfluous — remove it or set it to auto.
#progress {
animation: grow-progress linear forwards;
animation-timeline: scroll();
}
One ordering gotcha: animation-timeline cannot be set through the animation shorthand. Bramus calls it a "reset-only sub-property of the shorthand," meaning the shorthand resets its value the way background resets background-color. Declare animation-timeline after animation.
/* YEP! */
#progress {
animation: grow-progress linear forwards;
animation-timeline: scroll();
}
/* NOPE! */
#progress {
animation-timeline: scroll();
animation: grow-progress linear forwards;
}
The scroll() function accepts configuration for both axis and scroller:
animation-timeline: scroll(<axis> <scroller>);
<axis>:block(default),inline,y, orx.<scroller>:nearest(default),root(the document), orself.
If the root element does not overflow, the animation is inactive. The same timeline can be created imperatively through WAAPI's ScrollTimeline.
const $progressbar = document.querySelector(#progress);
$progressbar.style.transformOrigin = '0% 50%';
$progressbar.animate(
{
transform: ['scaleX(0)', 'scaleY()'],
},
{
fill: 'forwards',
timeline: new ScrollTimeline({
source: document.documentElement, // root element
// can control `axis` here as well
}),
}
)
View timelines from view() and ViewTimeline
Two terms need separating first: the scroll container and the scrollport. A scrollport is the visible region and coincides with the scroll container's padding-box; once a scrollbar is present, it plus the scroll container make up the scroller.

A view timeline tracks how a subject sits relative to the scrollport — conceptually close to IntersectionObserver, but continuous. The common example is revealing images in long-form content as they enter the viewport:
@keyframes reveal {
from {
opacity: 0;
clip-path: inset(45% 20% 45% 20%);
}
to {
opacity: 1;
clip-path: inset(0% 0% 0% 0%);
}
}
.revealing-image {
animation: reveal 1s linear both;
}
Swapping in the view() function registers a view timeline, so the animation responds to the image's visibility:
.revealing-image {
animation: reveal 1s linear both;
/* Remember to declare the timeline after the shorthand */
animation-timeline: view();
}
At that point the reveal completes only once the element has fully exited, so part of the effect is never seen. One fix is to end the keyframes at the 50% mark; a cleaner solution comes later.
Arguments to view():
animation-timeline: view(<axis> <view-timeline-inset>);
The <axis> behaves as with scroll(). <view-timeline-inset> adjusts the visibility range that defines progress and takes auto (the default) or a <length-percentage>; positive insets adjust outward and negative ones inward. Note the absence of a <scroller> argument — a view timeline always tracks its subject's nearest ancestor scroll container. ViewTimeline offers the same capability in JavaScript:
const $images = document.querySelectorAll(.revealing-image);
$images.forEach(($image) => {
$image.animate(
[
{ opacity: 0, clipPath: 'inset(45% 20% 45% 20%)', offset: 0 }
{ opacity: 1; clipPath: 'inset(0% 0% 0% 0%)', offset: 0.5 }
],
{
fill: 'both',
timeline: new ViewTimeline({
subject: $image,
axis: 'block', // Do we have to do this if it's the default?
}),
}
}
)
Attachment ranges and keyword points
Rather than rebuild keyframes or fiddle with insets, shorten the attachment range with animation-range. The defaults span zero to full scroll:
animation-range: normal normal;
animation-range: 0% 100%;
The values may be any length units:
animation-range: 100px 80vh;
A fuller example animates a full-height cover card into a slim fixed header. Applied naively, the animation consumes the entire 0%–100% range:
@keyframes sticky-header {
from {
background-position: 50% 0;
height: 100vh;
font-size: calc(4vw + 1em);
}
to {
background-position: 50% 100%;
height: 10vh;
font-size: calc(4vw + 1em);
background-color: #0b1584;
}
}
.sticky-header {
position: fixed;
top: 0;
animation: sticky-header linear forwards;
animation-timeline: scroll();
}
Narrowing the range keeps the header from animating out of sight; subtracting the header's final 10vh from the full 100vh yields 90vh:
.sticky-header {
position: fixed;
top: 0;
animation: sticky-header linear forwards;
animation-timeline: scroll();
animation-range: 0vh 90vh;
}
A performance caveat applies here: font-size animates on the main thread and is not hardware-accelerated, so an animation involving it — or one touching custom properties — runs on the main thread entirely. The range itself has four points, not two, and view timelines cover the larger area between the start and end edges. That means this:
animation-range: 0% 100%; /* same as 'normal normal' */
is equivalent to:
animation-range: cover 0% cover 100%; /* 'cover normal cover normal' */
and ultimately resolves to:
animation-range: cover;
The reveal example could therefore have been written without new keyframes or insets:
animation-range: cover 0% cover 50%;
A visualization lives at scroll-driven-animations.style. Keyword values are available: contain, entry, exit, entry-crossing, and exit-crossing.

contain
entry
exitWhen a subject is taller than the scrollport, the ranges shift, which brings entry-crossing and entry-exit into play. Multiple scroll-driven animations on one page are fine as long as their ranges do not overlap; a contact-list demo animates items on entry and exit. The same values can be declared directly in keyframes, eliminating the need for animation-range:
@keyframes animate-in {
entry 0% { opacity: 0; transform: translateY: 100%; }
entry 100% { opacity: 1; transform: translateY: 0%; }
}
@keyframes animate-out {
exit 0% { opacity: 1; transform: translateY: 0%; }
exit 100% { opacity: 0; transform: translateY: 100%; }
}
.list-view li {
animation: animate-in linear forwards,
animate-out linear forwards;
animation-timeline: view();
}
JavaScript exposes ranges as well:
const timeline = new ViewTimeline({
subjext: $li,
axis: 'block',
})
// Animate in
$li.animate({
opacity: [ 0, 1 ],
transform: [ 'translateY(100%)', 'translateY(0)' ],
}, {
fill: 'forwards',
// One timeline instance with multiple ranges
timeline,
rangeStart: 'entry: 0%',
rangeEnd: 'entry 100%',
})
Named timelines and lookup
Anonymous timelines track the nearest ancestor scroller, but a named timeline lets an animation follow any scroll container on the page. First, a trap. A container with overflow: hidden clips its content block to the padding box and offers no scrolling interface, yet its content remains programmatically scrollable — so it is still a scroll container. Prefer overflow: clip, which prevents the element from becoming a scroll container at all. Bramus no longer reaches for hidden unless he explicitly wants a scroller.
Another edge case: an absolutely positioned animation target inside a relatively positioned container can never match an outside scroller such as scroll(inline-nearest). Named timelines sidestep the guessing:
.gallery {
position: relative;
}
.gallery__scrollcontainer {
overflow-x: scroll;
scroll-timeline-name: --gallery__scrollcontainer;
scroll-timeline-axis: inline; /* container scrolls in the inline direction */
}
.gallery__progress {
position: absolute;
animation: progress linear forwards;
animation-timeline: scroll(inline nearest);
}
The shorthand compresses it:
.gallery {
position: relative;
}
.gallery__scrollcontainer {
overflow-x: scroll;
scroll-timeline: --gallery__scrollcontainer inline;
}
.gallery__progress {
position: absolute;
animation: progress linear forwards;
animation-timeline: scroll(inline nearest);
}
block is the initial value of scroll-timeline-axis, and the timeline name is a dashed-ident that resembles a CSS variable. Named view timelines work the same way:
.scroll-container {
view-timeline-name: --card;
view-timeline-axis: inline;
view-timeline-inset: auto;
/* view-timeline: --card inline auto */
}
Apple's old cover-flow effect, recreated in a demo, attaches two animations — image rotation and z-index — to a single shared view timeline, replacing per-element tracking of the nearest scroller:
.covers li {
view-timeline-name: --li-in-and-out-of-view;
view-timeline-axis: inline;
animation: adjust-z-index linear both;
animation-timeline: --li-in-and-out-of-view;;
}
.cards li > img {
animation: rotate-cover linear both;
animation-timeline: --li-in-and-out-of-view;;
}
In that demo the images rotate and scale, but the view timeline keeps respecting the original box size rather than resizing with the flexing elements. For timelines that are not direct ancestors of the target, timeline-scope placed on a shared parent lets the two remain connected, and it accepts several comma-separated values. The all keyword has no Safari or Firefox support yet.
timeline-scope: --one, --two, --three;
/* or */
timeline-scope: all; /* Chrome 116+ */
Named timelines also have a defensive advantage over anonymous ones in real layouts.
Demo: scroll shadows that only appear when needed
Replacing the classic multiple-gradient approach pinned with background-attachment: fixed, this version uses pseudos with sticky positioning:
.container::before,
.container::after {
content: "";
display: block;
position: sticky;
left: 0em;
right 0em;
height: 0.75rem;
&::before {
top: 0;
background: radial-gradient(...);
}
&::after {
bottom: 0;
background: radial-gradient(...);
}
}
CSS animation fades the shadows in and out, and while the demo uses a named timeline, an anonymous one would also do:
@keyframes reveal {
0% { opacity: 0; }
100% { opacity: 1; }
}
.container {
overflow:-y auto;
scroll-timeline: --scroll-timeline block; /* do we need `block`? */
&::before,
&::after {
animation: reveal linear both;
animation-timeline: --scroll-timeline;
}
}
Each pseudo's range is set to start where its shadow belongs. The top edge is straightforward:
.container::before {
animation-range: 1em 2em;
}
The bottom edge is trickier: it should begin after 2em of scrolling and travel only 1em, so the animation is reversed and the range computed from the bottom edge.
.container::after {
animation-direction: reverse;
animation-range: calc(100% - 2em) calc(100% - 1em);
}
Shadows should appear only when the container actually scrolls; a box taller than its content triggers both despite nothing to scroll. An animation-timeline keyword handles this: detect-scroll derives a boolean custom property, --can-scroll, which gates the pseudos' visibility.
@keyframes detect-scroll {
from,
to {
--can-scroll: ; /* value is a single space and acts as boolean */
}
}
.container {
animation: detect-scroll;
animation-timeline: --scroll-timeline;
animation-fill-mode: none;
}
.content::before,
.content::after {
--vis-if-can-scroll: var(--can-scroll) visible;
--vis-if-cant-scroll: hidden;
visibility: var(--vis-if-can-scroll, var(--vis-if-cant-scroll));
}
Demo: columns scrolling in opposite directions
A three-column grid where the outer columns move against the inner one. The outer columns are pushed upward so their bottom edges align with the viewport's top edge, then slide down on scroll until their top edges meet the viewport's bottom edge.
<div class="columns">
<div class="column reverse">...</div>
<div class="column">...</div>
<div class="column reverse">...</div>
</div>
The columns sit in a grid container and flex in the column direction.

The animation, and the equivalent JavaScript approach:
@keyframes adjust-position {
from /* the top */ {
transform: translateY(calc(-100% + 100vh));
}
to /* the bottom */ {
transform: translateY(calc(100% - 100vh));
}
}
.column-reverse {
animation: adjust-position linear forwards;
animation-timeline: scroll(root block); /* viewport in block direction */
}
const timeline = new ScrollTimeline({
source: document.documentElement,
});
document.querySelectorAll(".column-reverse").forEach($column) => {
$column.animate(
{
transform: [
"translateY(calc(-100% + 100vh))",
"translateY(calc(100% - 100vh))"
]
},
{
fill: "both",
timeline,
}
);
}
Demo: 3D model and scroll velocity
An animation is attached to a 3D model custom element without initial keyframes:
<model-viewer alt="Robot" src="robot.glb"></model-viewer>
@keyframes foo {
}
model-viewer {
animation: foo linear both;
animation-timeline: scroll(block root); /* root scroller in block direction */
}
Rotation and orientation come from JavaScript, which reads progress from the animation's effect rather than its current time — the time value is always relative to the full range, so the effect is needed for progress under the applied animation:
// Bramus made a little helper for handling the requested animation frames
import { trackProgress } from "https://esm.sh/@bramus/sda-utilities";
// Select the component
const $model = document.QuerySelector("model-viewer");
// Animation begins with the first iteration
const animation = $model.getAnimations()[0];
// Variable to get the animation's timing info
let progress = animation.effect.getComputedTiming().progress * 1;
// If when finished, $progress = 1
if (animation.playState === "finished") progress = 1;
progress = Math.max(0.0, Math.min(1.0, progress)).toFixed(2);
// Convert this to degrees
$model.orientation = `0deg 0deg $(progress * -360)deg`;
The most experimental segment detects scroll speed and direction in pure CSS. Bramus labels it explicitly a hack, and not a particularly performant one. Two registered custom properties can be interpolated:
@keyframes adjust-pos {
from {
--scroll-position: 0;
--scroll-position-delayed: 0;
}
to {
--scroll-position: 1;
--scroll-position-delayed: 1;
}
}
:root {
animation: adjust-pos linear both;
animation-timeline: scroll(root);
}
@property --scroll-position {
syntax: "<number>";
inherits: true;
initial-value: 0;
}
@property --scroll-position-delayed {
syntax: "<number>";
inherits: true;
initial-value: 0;
}
Application to body is essential to the trick: it depends on the parent-child relationship between html and body. The parent updates immediately while the child lags slightly behind, so both evaluate equal, differing only in when they start. A delay staggers them further:
:root {
animation: adjust-pos linear both;
animation-timeline: scroll(root);
}
body {
transition: --scroll-position-delayed 0.15s linear;
}
The gap between the two staggered values is the velocity:
:root {
animation: adjust-pos linear both;
animation-timeline: scroll(root);
}
body {
transition: --scroll-position-delayed 0.15s linear;
--scroll-velocity: calc(
var(--scroll-position) - var(--scroll-position-delayed)
);
}
Zero means no scrolling, since the values are in sync; a positive number means downward scrolling, a negative one upward. Abrupt direction changes produce a small discrepancy, correctable by tightening the --scroll-position-delayed transition delay, though that inflates velocity and may call for a multiplier — hence "hack." A math-function variant exists, but note that Chrome did not yet support sign() or abs() at recording time without enabling chrome://flags; Ana Tudor's polyfill for the math functions covers that gap.
body {
transition: --scroll-position-delayed 0.15s linear;
--scroll-velocity: calc(
var(--scroll-position) - var(--scroll-position-delayed)
);
--scroll-direction: sign(var(--scroll-velocity));
--scroll-speed: abs(var(--scroll-velocity));
}
With velocity in hand, an element could be skewed or have its background saturation adjusted by scroll speed, optionally through style queries.
@container style(--scroll-direction: 0) { /* idle */
.slider-item {
background: crimson;
}
}
@container style(--scroll-direction: 1) { /* scrolling down */
.slider-item {
background: forestgreen;
}
}
@container style(--scroll-direction: -1) { /* scrolling down */
.slider-item {
background: lightskyblue;
}
}


