# Scroll-Driven Animations

- **Canonical URL:** https://frontend.rocks/concepts/scroll-driven-animations/
- **Domain:** Rendering Pipeline
- **Baseline / Maturity Status:** Experimental
- **Last Verified:** 2026-11-15
- **TL;DR:** animation-timeline: scroll() and view() bind CSS and WAAPI animations directly to scroll progress on the Compositor Thread.

## Prerequisites
- [Web Animations API (WAAPI)](https://frontend.rocks/concepts/web-animations-api.md): Scroll-driven timelines plug into the same Web Animations timing model.
- [GPU Compositor Layers and will-change](https://frontend.rocks/concepts/gpu-compositor-layers.md): Scroll progress updates on the Compositor Thread without main-thread scroll listeners.

## Primary Sources
- https://drafts.csswg.org/scroll-animations-1/
- https://developer.mozilla.org/en-US/docs/Web/CSS/animation-timeline

---
## TL;DR

Scroll-Driven Animations replace `scroll` event listeners with native timelines: `scroll()` tracks a container's scroll offset, while `view()` tracks an element's visibility inside its scrollport. Both run on the Compositor Thread at full display refresh rate.

## Interactive Lab

Compare a main-thread `scroll` listener against `animation-timeline: scroll()` in `PatternComparatorLab`.

## Under the Hood

A JS scroll listener is a backseat driver shouting coordinates over a walkie-talkie; `animation-timeline` wires the speedometer directly to the axle.

1. **Timeline Replacement**: Instead of wall-clock time, [Web Animations API](/concepts/web-animations-api) timelines sample progress from `0%` to `100%` based on scroll offset.
2. **Compositor Execution**: When animating [GPU Compositor Layers](/concepts/gpu-compositor-layers) properties like `transform: scaleX()` or `opacity`, the Compositor Thread updates pixels without waking the main thread.
3. **Named Ranges**: `animation-range: entry 0% cover 40%` scopes `view()` animations to exact entry and exit phases.

```css
@supports (animation-timeline: view()) {
  .reveal-card {
    animation: fade-slide linear both;
    animation-timeline: view();
    animation-range: entry 0% entry 80%;
  }
}
```

## Problem Genealogy

- **2013–2022**: Parallax and reading-progress bars relied on throttled `scroll` handlers or `IntersectionObserver` + rAF, lagging one frame behind async compositor scrolling.
- **2023+**: CSS Scroll-Driven Animations introduced `scroll()` and `view()` timelines in Chromium, with Safari 26 following and Firefox implementing.

## Production Pitfalls

- **Missing `@supports` guard**: Setting `opacity: 0` at `0%` leaves elements permanently invisible in browsers lacking `animation-timeline` support.
- **Animating `width` instead of `scaleX()`**: Using `width` forces Layout on every scroll tick, forfeiting compositor offloading.
- **When not to use Scroll-Driven Animations**: Do not use them for critical navigation state or binary sticky-header triggers where `IntersectionObserver` or `position: sticky` suffices.
