CSS scroll-timeline-name Property

If this site has been useful, we’d love your support! Consider buying us a coffee to keep things going strong!

Description

The scroll-timeline-name property defines a named scroll timeline that can later be referenced by animations. It acts as an identifier that connects a scrolling container (or the root scroller) to animations that react to scroll progress rather than time. By assigning a name to a scroll timeline, you make it reusable and decoupled from the animation itself, allowing multiple animations to respond to the same scroll-driven progression. This separation improves clarity and maintainability, especially in complex interfaces where multiple elements react to a single scrolling context.

The primary purpose of scroll-timeline-name is to establish a link between scrolling behavior and animation logic without hard-wiring those relationships directly into animation definitions. Once defined, the name can be referenced by other animation-related properties, enabling animations to advance based on how far the user has scrolled rather than elapsed time. This model makes scroll-driven animations more declarative and predictable, particularly when combined with properties like animation-timeline, which determines which timeline an animation should follow. Together, they allow animations to be synchronized with user interaction in a clean and readable way.

Another important aspect of scroll-timeline-name is how it fits into layout-aware animation design. It works alongside properties such as scroll-timeline-axis, which defines the scroll direction that drives the timeline, and can also complement view-based timelines created using view-timeline-name. This makes it possible to create rich, responsive animations that react naturally to scrolling context - such as revealing content, animating progress indicators, or coordinating motion across multiple elements - without relying on JavaScript. By naming timelines explicitly, developers gain greater control, reuse, and clarity when building advanced scroll-driven animation systems.

Definition

Initial value: none
Applies to: all elements
Inherited: no
Computed value: the keyword none or a list of CSS identifiers
Animatable: no
JavaScript syntax: object.style.scrollTimelineName

Syntax

scroll-timeline-name: [ none | <dashed-ident> ]#

Values

noneThe default value. No scroll timeline is defined for the element.
<dashed-ident>A custom name for the timeline. It must start with two dashes (e.g., --my-scroller). This acts as the unique ID that your animation will reference.

Example

HTML

<div class="scroll-container">

  <div class="progress-bar"></div>

  <div class="content">

    <h1>Scroll Down</h1>

    <p>The bar at the top will grow as you move through this text.</p>

    <div class="spacer"></div>

    <p>Keep going...</p>

    <div class="spacer"></div>

    <p>You've reached the end!</p>

  </div>

</div>

CSS

/* 1. Define the Scroll Container */
.scroll-container {
  height: 400px;
  overflow-y: scroll;
  border: 2px solid #333;
  position: relative;
  
  /* Create the timeline name here */
  scroll-timeline-name: --my-scroll-timeline;
  /* Define the axis (vertical) */
  scroll-timeline-axis: block;
}

/* 2. The element that will animate */
.progress-bar {
  position: sticky;
  top: 0;
  left: 0;
  height: 10px;
  background-color: #007bff;
  width: 0%; /* Start at 0 */
  
  /* Link the animation to the named timeline */
  animation: grow-progress auto linear;
  animation-timeline: --my-scroll-timeline;
}

/* 3. The Animation */
@keyframes grow-progress {
  from { width: 0%; }
  to { width: 100%; }
}

/* Visual styling for the demo */
.content {
  padding: 20px;
}
.spacer {
  height: 600px; /* Makes the container scrollable */
  background: linear-gradient(transparent, #f0f0f0);
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS scroll-timeline-name property. Hover over a browser icon to see the version that first introduced support for this CSS property.