animation-timeline | CSS-Tricks

Experimental: Check browser support before using this in production.
The animation-timeline CSS property controls the progress of animations using timelines beyond the traditional document timeline. Typically, CSS animations progress based on the amount of time passed in the document’s default timeline, which begins when the page is loaded. With animation-timeline however, you can link an animation’s progression to scrolling or when an element is visible in the viewport, which are different types of timelines.
At its core, animation-timeline simply connects an animation’s progress to one of these timelines. This is super useful, as it allows you to create scroll-based and other animations based on when something enters the screen.
The dashed-ident is a case-sensitive identifier that begins with two dashes (--) followed by a name you specify. In this case, it refers to a named timeline previously declared with the scroll-timeline-name or view-timeline-name properties.
The scroll progress timeline measures the distance a user has scrolled within a container that allows scrolling. Think of it as a progress bar tied to the user’s scroll position. The position is converted into a percentage value which is then used for the animation progression.
We call this scroll container the “reference container” and it can be specified either through a named scroll progress timeline or anonymously. Let’s break down the differences between named and anonymous timelines.
A named scroll progress timeline is a timeline that you give a name to. You literally provide a name for the timeline using the scroll-timeline-name property:
From there, we can use the animation-timeline property to link the scroll-timeline-name to the element that is being animated.
And finally, we can create the animation:
…and then apply that animation to the animated element:
As of the time of this writing, Firefox requires the animation-duration property to be set on the animated element for the scroll animation to work:
Unlike named scroll timelines that we name ourselves, an anonymous scroll timeline does not have an explicit name. It’s implied. And we imply it using the scroll() function:
Notice how we do not have to set a scroll-timeline-name anywhere. Instead, we’re telling CSS that the element we’re animating is a scroll animation using the scroll() function. This function links the animation to a specific scroll container element (called the “scroller”) and its movement along either the horizontal x-axis or the vertical y-axis.
Here’s the same effect as the named example, using scroll() instead:
So, rather than giving the scroll container an explicit name, we’re simply telling CSS that the image element follows the scroll() timeline of the nearest scroll container, which in this case, is the .scroll-container element. That’s the difference between an anonymous scroll timeline like this and one that we name.
The second type of timeline we can link is not based on scrolling, but when an element is visible in what we call the “scrollport” and where it is in the scrollport.
So, what exactly is the scrollport? It’s the visible, scrollable area of a scrolling container. Think of it as the part of the container you can see and scroll, minus any padding, borders, or scrollbars.
A view timeline tracks the relative position of a subject within a scrollport. If you’re familiar with the Intersection Observer in JavaScript, then you already have a good idea of view timelines in CSS because they essentially work the same.
We can begin an animation on the scroll timeline when an element intersects with another, element such as the target element intersecting the viewport, then it progresses with scrolling.
With view timelines, the animation only starts and progresses when the element is visible, keeping everything perfectly in sync.
Similar to scroll timelines, a named view timeline is explicitly linked to an element using the view-timeline-name property and then referenced with animation-timeline for animations. The key difference here is that the subject (the element controlling the timeline) doesn’t have to be the same as the target (the element being animated).
This provides great flexibility because:
For example, you could fade in a “scroll to top” button once a specific section is visible, or have a caption slide in when its corresponding image enters the viewport. Let’s take a look at a basic example:
In this example, the image scales up from 0 to 1 as you scroll through the scrollport. The subject and the target are the same element in this example — the image — since the animation is applied based on the image’s progress up through the scroller.
You may notice that the view timeline animation finishes just as the element exits the viewport — this is because the timeline’s progress reaches 100% at that point. As a result, you don’t get to see the complete animation. The proper way to address this is by using the animation-range property. See the “Timeline Ranges Demystified” section in the article “Unleash the Power of Scroll-Driven Animations” for an explanation of how it is used to fine-tune the progress of scroll animations.
Just like scroll timelines have the scroll() function for linking anonymous timelines, view timelines have the view() function for anonymous view timelines. And the concept is the same, only it is based on the target element’s position in the scrollport. It allows an element (the subject) to animate based on its visibility progress within its closest scrollable container (scroller). You can choose which axis — vertical or horizontal — and the animation progress is tracked from there.
Unlike scroll(), the view() function always uses the element’s nearest scrollable ancestor as the scroller, so you don’t need to define one manually. By default, the axis is block, and the inset is auto (no adjustments).
For example, converting the named view timeline example we discussed earlier to an anonymous one:
In this secti