The Scroll-Linked Animations specification offers an experimental way to drive CSS animations by scrolling. Previously, such effects required a JavaScript library, but this spec sets itself apart in two ways: it exposes both a JavaScript interface and a CSS one, and the animations run on the compositor, keeping work off the main thread. This article focuses on the CSS side.
The three pieces of a scroll-linked animation
A basic implementation consists of a regular CSS animation, a scroll timeline, and a link between them. The animation is defined as usual and attached to an element with the animation property.
@keyframes adjust-progressbar {
from {
transform: scaleX(0);
}
to {
transform: scaleX(1);
}
}
#progressbar {
animation: 1s linear forwards adjust-progressbar;
}
The scroll timeline, declared with the @scroll-timeline at-rule, maps scroll distance to animation progress. Besides a name, it accepts several descriptors:
source— the scrollable element whose scrolling activates and drives the timeline. It defaults toauto, meaning the entire document.orientation— the scroll direction that triggers the animation;verticalby default.scroll-offsets— the key points delimiting the range in which the animation is active. These can be relative or absolute values (percentages or lengths) or element-based offsets.
@scroll-timeline scroll-in-document-timeline {
source: auto;
orientation: vertical;
scroll-offsets: 0%, 100%;
}
An earlier version of the spec required a time-range descriptor. That has since been removed: the timeline now takes the animation-duration of the linked animation automatically, so any lingering references to it in demos can be ignored.
Linking the two is the job of the animation-timeline property, which points at the timeline's name. With that in place, the adjust-progressbar animation no longer plays on page load; it advances only as the page is scrolled down.
#progressbar {
animation: 1s linear forwards adjust-progressbar;
animation-timeline: scroll-in-document-timeline;
}
Element-based offsets, which drive an animation as an element enters and leaves the scrollport, are covered in depth in parts 1 and 2 of the author's series on the subject.
Common patterns
Beyond the progress bar, several scenarios fit the approach: a parallax header, image reveal and hide, typing animations, carousel indicators, and scrollspy. Each one is built from the same three parts.
Parallax header
The classic use case is a parallax effect, in which sections appear to scroll at different speeds. It can be done in CSS alone, but only through transform hacks involving translate-z() and scale(). Reproducing the Firewatch Header demo with a scroll timeline removes that hack, along with the extra .parallax__cover element.
Everything else stays broadly similar: the <body> gets a min-height to provide scroll estate, and the positioning of .parallax and its .parallax_layer children is adjusted. All layers share one timeline covering a scroll distance of 100vh.
@scroll-timeline scroll-for-100vh {
scroll-offsets: 0, 100vh;
}
.parallax__layer {
animation: 1s parallax linear;
animation-timeline: scroll-for-100vh;
}
What differs per layer is how far it travels: the back layer stays put (0vh), the front layer moves the full 100vh, and layers in between are interpolated. Since the front layers travel farther over the same scroll range, they appear to move faster.
@keyframes parallax {
to {
transform: translateY(var(--offset));
}
}
.parallax__layer__0 {
--offset: 100vh;
}
.parallax__layer__1 {
--offset: 83vh;
}
.parallax__layer__2 {
--offset: 67vh;
}
.parallax__layer__3 {
--offset: 50vh;
}
.parallax__layer__4 {
--offset: 34vh;
}
.parallax__layer__5 {
--offset: 17vh;
}
.parallax__layer__6 {
--offset: 0vh;
}
Image reveal
An image can reveal itself as it enters the viewport. The starting state sets an opacity of 0 and applies a clip-path mask, with the end keyframe defining the fully visible state.
#revealing-image {
opacity: 0;
clip-path: inset(45% 20% 45% 20%);
}
@keyframes reveal {
to {
clip-path: inset(0% 0% 0% 0%);
opacity: 1;
}
}
@scroll-timeline revealing-image-timeline {
scroll-offsets:
selector(#revealing-image) end 0.5,
selector(#revealing-image) end 1
;
}
#revealing-image {
animation: reveal 1s linear forwards;
animation-timeline: revealing-image-timeline;
}
Using element-based offsets means the reveal only begins once the image itself slides into view. A separate visualization tool exists for anyone who finds those offsets hard to follow.
Typing on scroll
Because a scroll timeline can be attached to any existing CSS animation, existing demos can be converted with little work. A typing animation gains a timeline plus the animation-timeline property and types as the reader scrolls; a <body> height of 300vh supplies the scroll estate. Swapping in a different animation yields a zoom-on-scroll effect instead. Both suit article intros.
Slider indicators
Carousels usually expose slide count and position with bullets. Fabrizio Calderan's demo injects the active-state bullet via .slider nav::before, then animates it across the other bullets. A @scroll-timeline attached to the slider lets that dot follow the scroll position.
/* Styling of the dots */
.slider nav::before, .slider a {
inline-size: 1rem;
aspect-ratio: 1;
border-radius: 50%;
background: #9bc;
}
/* Positioning of the active dot */
.slider nav::before {
content: "";
position: absolute;
z-index: 1;
display: block;
cursor: not-allowed;
transform: translateX(0);
animation: dot 1s steps(1, end) 0s forwards;
}
/* Position over time of the active dot */
@keyframes dot {
0%
{ transform: translateX(0); }
33%
{ transform: translateX(calc((100% + var(--gap)) * 1)); }
66%
{ transform: translateX(calc((100% + var(--gap)) * 2)); }
100%
{ transform: translateX(calc((100% + var(--gap)) * 3)); }
}
@scroll-timeline slide {
source: selector(#s);
orientation: inline;
}
.slider nav::before {
/* etc. */
animation-timeline: slide;
}
A steps() function in the animation keeps the dot still until a slide has snapped into place. Remove it and the dot visibly tracks the scroll instead. The technique looks like the last missing piece for a CSS-only carousel.
Scrollspy
A sticky table of contents with scrolling active states originally relied on IntersectionObserver to toggle the active item. It cannot be reduced to moving a single dot, since text items change appearance. Instead, each ToC element carries two animations: one activates the item when its section enters at the bottom edge of the document, the other deactivates it when the section exits at the top edge.
.section-nav li > a {
animation:
1s activate-on-enter linear forwards,
1s deactivate-on-leave linear forwards;
}
Two animations mean two scroll timelines per content section. For #introduction, for example:
@scroll-timeline section-introduction-enter {
scroll-offsets:
selector(#introduction) end 0,
selector(#introduction) end 1;
}
@scroll-timeline section-introduction-leave {
scroll-offsets:
selector(#introduction) start 1,
selector(#introduction) start 0;
}
.section-nav li > a[href"#introduction"] {
animation-timeline:
section-introduction-enter,
section-introduction-leave;
}
Availability
The features described here are experimental and not finalized. No browser supports them at the time of writing, except Chromium 89 and later with the "Experimental Web Platform Features" flag enabled. Those who want scroll-linked animations in other engines can star the relevant tracking issues in Chromium, Firefox, and Safari; doing so signals developer interest to the vendors.



