Scroll-timeline - Property CSS

scroll-timeline

scroll-timeline-axis

scroll-timeline-name

Summary of characteristics of the `scroll-timeline` property

Quick description

A short hand property that defines the parameters of a scroll-driven animation.

Status

Standard

Usable for

HTML

Predefined values

none

Percentages

See individual properties.

Initial value

See individual properties.

Inherited by default

No.

Animation type

Not animable : the scroll-timeline property cannot be animated.

W3C Module

Scroll-driven Animations

References (W3C)

Scroll-driven Animations - Level 1

Document status: WD (Working Draft)

Syntax diagram of `scroll-timeline`.

Syntax diagram of the scroll-timeline property.
The links in the diagram provide more details about the values.

In the diagram, the bold terms are the predefined words of CSS, the other terms are described below:

--id is an identifier chosen by the user. Its name must begin with a double hyphen.

Description of the `scroll-timeline` property.

scroll-timeline is a short hand property, allowing you to define the values for the following properties in a single write:

scroll-timeline-axis: Specifies which axis (vertical or horizontal) should synchronize the scroll-driven animation.
scroll-timeline-name: Sets an identifier for a scroll-driven animation.

Both of these properties (and therefore also the shorthand property scroll-timeline) apply to a scrollable container, i.e. an element whose overflow property has been set to scroll or auto. They define how this container will be able to drive an animation. The --id can then be used on a child element of the container, or on the container itself, with the animation-timeline property.

Use of scroll-timeline

Simple example of use:


	/* Definition of animation */
	@keyframes rotation {
	   from {rotate:0deg;}
	   to {rotate:90px;}
	}
	
	/* Container rules */
	#de1-container {
	   height:100px;
	   overflow:scroll;
	   scroll-timeline: --demo block;
	}
	
	/* Rules applied to the animated element */
	#de1-image {
	   animation:rotation 1ms linear;
	   animation-timeline:--demo;
	}

Here's what it looks like on an example. The scrollable container contains an image of a balloon. The latter is animated (rotate). As you scroll through the vertical scroll bar, you'll see the balloon spin.

⚠ This example does not work on the Firefox browser unless you have enabled the flag layout.css.scroll-driven-animations.enabled.

Click this link for a more complete overview of scroll-driven animations.

See also the scroll-timeline-name , scroll-timeline-axis , animation-timeline and view-timeline properties, and the scroll() and view() functions which allow you to define a scroll-driven animation anonymously, without the need to define an identifier.

Values for `scroll-timeline`.

scroll-timeline: none;

The element is not or is no longer a driver for animations.
scroll-timeline: --id block;

This syntax defines the --id identifier for controlling animation along the block axis. It's actually a combination of the syntaxes scroll-timeline-name and scroll-timeline-axis.
scroll-timeline: --id1 block, --id2 inline;

Several definitions can follow one another, separated by a comma.
scroll-timeline: initial; scroll-timeline: inherit; scroll-timeline: revert; scroll-timeline: revertLayer; scroll-timeline: unset;

See the following pages for more details: initial, inherit, revert, revert-layer, unset.

Scroll-Driven Animation Tutorial.

General information.

CSS animations consist of changing the value of one or more properties between a minimum and maximum value. For example, we request that the brightness of the background color change from 20% to 80% (see @keyframes ). These animations are typically time-driven: simply define the total duration of the animation with the animation-duration property. For our example, let's consider a 30-second animation (which is very long). We can then establish a relationship between time and brightness.

Time-Driven Animation

A new type of animation is now possible: scroll-driven animations, which consist of driving the animation from an element The element must of course allow scrolling (see the overflow property). The value of the animated property is then defined by the percentage Scroll applied to this element.

Scroll-driven animation

The animation can be controlled by either the vertical or horizontal scrolling. The scroll-timeline-axis property and the shorthand property scroll-timeline property are used to define which scroll bar should be used to drive the animation.

Two approaches: `scroll` and `view`.

The short hand properties scroll-timeline and view-timeline define a driver for animations, with two different logics:

scroll-timeline: the animation is driven by the position of a scroll bar. This property must be applied to the container with scroll bars.
Animations can be applied to one descendant elements of that container or to the scrolling container itself.
view-timeline: The animation is driven by the position of an element in a scrolling container as long as that element is visible.
Animations can be applied to this scrolling container, or one of its descendants.

In both cases, the link between the animation and the driver is done with the animation-timeline property, which is used on the animated element. On the diagram below, elements that can be animated are identified by a circular arrow.

The animation is associated with
the scroll bar.

The animation is associated with
the visibility of the blue element.

Non-top-down animations.

We can see that animations can only be used on the descendant elements of the scrolling container or on the scrolling container itself. However, you can consider using a driver on elements that are not descendants of the scrolling container, using the timeline-scope. This property must be set to a parent that is common to scrolling containers and animated elements.

This is what has been done with the example below. Three rotations are possible for the dice, each controlled by a cursor. These are provided by scrolling elements that are not parents of the dice. But a common parent has been given the timeline-scope property.

The three elements cube1, cube2 and cube3 are each animated along one of the axes.

Scroll-driven animations - Anonymous syntax.

This simplified syntax requires only one rule, with the animation-timeline property and one of the scroll() or view() functions. This rule must be applied to the animated element, and the animated element must have a parent (direct or indirect) that accepts scrolling, or accepts scrolling itself.

Animated element following its own scroll

Animated element following the scrolling
of the nearest scrolling container

Here's a small example: the color of the tu4-content element is driven by the horizontal scrolling of the parent tu4-container element. Just use the animation-timeline property on the animated element.
At the moment (2024) this example does not work on Firefox.

Note 1: it is also possible to control the animation according to the scrolling of the root element of the page.
Note 2: Equivalent syntaxes are found with the view() function.

Impact on other animation properties.

Setting animation-timeline inactivates the animation-duration property. Conversely, the animation-range property is enabled. The other animation properties retain their role, or not, according to the table below.

	Time-driven animations	Scroll-driven animations
`animation-composition`	Normal
`animation-delay`	Normal	No effect ⁽¹⁾
`animation-direction`	Normal	No effect
`animation-duration`	Normal	No effect ⁽¹⁾
`animation-fill-mode`	Normal
`animation-iteration-count`	Normal	No effect
`animation-name`	Normal
`animation-play-state`	Normal
`animation-range`	No effect	Normal
`animation-timing-function`	Normal

(1) However, if animation-delay is set, animation-delay causes a delay in starting the animation

Learn more...

A tutoriel on animations in CSS.
The definition of an animation with @keyframes .
Properties to define a driver: scroll-timeline and view-timeline .
Associating a pilot with an animation with animation-timeline .
The functions scroll() et view() .
The property timeline-scope.

Animation of the `scroll-timeline` property.

It is not possible to animate any of the properties that participate in defining animations. This is the case of scroll-timeline, scroll-timeline-name and scroll-timeline-axis.

Simulator.

The simulator allows you to choose a value for scroll-timeline-axis. The value of scroll-timeline-name is already set and an animation scroll-driven (a rotation) is applied to the balloon image.

scroll-timeline-axis :

block

inline

x

y

Browsers compatibility with `scroll-timeline`.

On Firefox , support for these properties is disabled by default. It can be activated by positioning the flag layout.css.scroll-driven-animations.enabled to true (access flags on Firefox).

Column 1

Support for the scroll-timeline, short hand property, equivalent to scroll-timeline-name and scroll-timeline-axis.

Column 2

Support for the scroll-timeline-name property.

Column 3

Support for the scroll-timeline-axis property: define the axis used to drive animations.