View-timeline-name | CSS-Tricks

CSS Almanac → Properties → V → view-timeline-name

Geoff Graham on May 30, 2024

The CSS view-timeline-name property allows us to identify and reference an element we want to animate based on its scroll position when it enters the visible area (i.e., scrollport) of a scroll container (also called the “source”).

.element {
  view-timeline-name: --image-zoom;
}

It’s a declarative way to trigger a scroll animation; otherwise, the element (also called the “subject”) will begin its scroll-based animation when it enters the scrollport of its nearest ancestor that has one.

The view-timeline-name property can also be declared using the view-timeline property, which is a shorthand that combines view-timeline-name and view-timeline-axis in a single declaration.

.element {
  view-timeline: --image-zoom y;

  /* Equivalent to: */
  view-timeline-name: --image-zoom;
  view-timeline-axis: y;
}

Syntax

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

Initial value: none
Applies to: All elements
Inherited: No
Percentages: N/A
Computed value: none or a list of CSS identifiers
Canonical order: By grammar
Animation: Not animatable

Property Values & Descriptions

/* Keyword value: none */
view-timeline-name: none;

/* <dashed-ident> examples */
view-timeline-name: --my-timeline;
view-timeline-name: --myTimeline;
view-timeline-name: --my_timeline;

none: The timeline does not have a name.
<dashed-ident>: A custom name given to a view progress timeline, like a <custom-ident>, that declaratively identifies it and distinguishes it from other timelines. The value is called a “dashed” ident because it must be prefixed with two dashes (--) exactly like we do for CSS custom properties, e.g. --image-zoom.

Scroll progress timelines vs. View progress timelines

The difference may seem small, but a scroll progress timeline is an animation we want to run on an element visible in the current scrollport, i.e. its scroll position whether scrolling vertically (the y-axis) or horizontally (the x-axis). When the element reaches a scroll position, the animation triggers and completes at the end of the scroll container. In other words, it’s an animation timeline that progresses from 0% to 100% as the user scrolls, whereas a typical animation timeline often happens when the page has been rendered.

That’s different from a view progress timeline which is a segment or part of a scroll progress timeline. In other words, a view progress timeline is sort of like the starting ignition of a scroll progress timeline, triggering the scroll progress timeline once the element (i.e., the “subject”) is currently in view.

Illustrating the pieces of an animation timeline, scroll progress timeline, and view progress timeline.

So, what we’re talking about is a scroll progress timeline that’s scoped to the element’s visibility in the current view. Once the element’s starting edge intersects with its nearest ancestor’s scrollport — which is a fancy way of saying “the visible part of a scroll container” — the animation is handed off to the scroll progress timeline and progresses by the user’s scrolling along whichever axis — x or y — is set.

Illustration of a scroll container on a webpage, including the visible scroll port and the element waiting to animate on scroll when entering the scroll port.

The <body> element can be considered a scroll container as long as it overflows what is currently in view. That means we can trigger or start an animation when the element we want to animate enters the visible area of the <body> after which point, the animation progresses based on the element’s scroll position.

A little terminology

It’s worth noting that there are some specific words that the specification uses to describe the various pieces of a scroll progress timeline.

Subject: The element we want to animate.
Source: The subject’s nearest ancestor (such as a parent or grandparent) with a scroll container that triggers and contains the animation up until the subject’s starting edge intersects with the source’s ending edge.

It’s cool that we have this sort of context, so we’ll continue using these terms along the way.

It’s a declarative way to define a view progress timeline

We don’t have to give a name to a view progress timeline. If we don’t it’s called an anonymous timeline and the subject we want to animate enters the progress timeline when it intersects with its nearest source. In other words, the animation is triggered when the element enters the visible part of the first scroll container it encounters.

Conversely, we can explicitly give the view progress timeline an identifying name with the view-timeline-name property to establish a declarative timeline that can be called and referenced by name. It’s what we reach for when we want the subject’s animation to kick off when it enters a super-specific source’s visible area.

Anonymous view progress timelines with `view()`

Even if we decide not to name a view progress timeline explicitly with scroll-timeline-name, it’s still possible to configure the view timeline behavior with the view() function. The function doesn’t take a scroll-timeline-name parameter, but it does instruct the browser what a subject should do when it intersects with its source.

.subject {
  animation-timeline: view(y 10dvh);
}

So, even without an explicit view-transition-name set on the subject element, we can still direct which view-timeline-axis the animation runs on and fudging exactly when it starts it starts with a view-timeline-inset parameter.

Specification

The view-timeline-name property is defined in the Scroll-driven Animations Module Level 1 specification, which is currently in Editor’s Draft status at the time of this writing. That means the work is under discussion and could change between now and when the proposal becomes a formal Candidate Recommendation.