CSS scroll-timeline-axis 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-axis property defines which physical direction of scrolling is used to drive a scroll-based animation timeline. In other words, it determines whether the animation’s progress responds to horizontal scrolling, vertical scrolling, or another logical axis tied to the writing mode of the document. This makes it a foundational piece of scroll-driven animations, as it directly controls how user movement through content maps to animation progression. Without this property, the browser would not know which scroll direction should influence the timeline when multiple axes are possible.

The property becomes especially important in layouts that are not strictly vertical. For example, horizontally scrolling galleries, carousels, or interfaces using vertical writing modes can all require a non-default scroll axis. By defining the axis explicitly, scroll-timeline-axis ensures that animations remain intuitive and predictable regardless of layout orientation. This allows designers to create motion that feels physically connected to the user’s scrolling behavior, rather than appearing arbitrary or disconnected.

In practice, scroll-timeline-axis works closely with properties that define what is being animated and when that animation occurs. For example, it commonly works alongside animation-timeline, which connects an animation to a scroll-driven timeline, and scroll-timeline-name, which identifies the timeline being referenced. It may also be influenced by layout-related properties such as writing-mode, since the meaning of “inline” or “block” directions can change depending on text flow. Together, these properties allow scroll-based animations to adapt seamlessly to different layouts, orientations, and reading directions while maintaining consistent behavior and visual clarity.

Definition

Initial value: block
Applies to: all elements
Inherited: no
Computed value: a list of the keywords specified
Animatable: no
JavaScript syntax: object.style.scrollTimelineAxis

Syntax

scroll-timeline-axis: [ block | inline | x | y ]#

Values

block(Default) Uses the scroll progress along the block axis. In a standard top-to-bottom layout, this is the vertical scroll.
inlineUses the scroll progress along the inline axis. In a standard left-to-right layout, this is the horizontal scroll.
xSpecifically targets the horizontal axis, regardless of writing mode.
ySpecifically targets the vertical axis, regardless of writing mode.

Example

HTML

<div class="scroll-container">

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

  <div class="content">

    <p>Scroll to the right to see the bar grow! →</p>

  </div>

</div>

CSS

/* 1. Define the scroll container */
.scroll-container {
  width: 400px;
  height: 200px;
  overflow-x: scroll;
  border: 2px solid #333;
  position: relative;
  
  /* Create the timeline and set the axis */
  scroll-timeline-name: --horizontal-scroll;
  scroll-timeline-axis: x; 
}

/* 2. The element we want to animate */
.progress-bar {
  height: 10px;
  background: #3498db;
  width: 0%; /* Start at 0 */
  position: sticky;
  top: 0;
  left: 0;
  
  /* Link the animation to our horizontal timeline */
  animation: grow-progress linear;
  animation-timeline: --horizontal-scroll;
}

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

/* Just making the content wide enough to scroll */
.content {
  width: 1200px;
  height: 100%;
  padding: 50px;
  background: linear-gradient(90deg, #eee 0%, #ccc 100%);
}

Result

Editor

Browser Support

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