timeline-scope CSS property

Syntax

/* Keyword values */
timeline-scope: all;
timeline-scope: none;

/* Custom name values */
timeline-scope: --custom_name_for_timeline;
timeline-scope: --timeline_name_one, --timeline_name_two;

/* Global values */
timeline-scope: inherit;
timeline-scope: initial;
timeline-scope: revert;
timeline-scope: revert-layer;
timeline-scope: unset;

Values

Allowed values for timeline-scope are:

none

There is no change in timeline scope. This is the default.

all

The names of all timelines defined by descendants are in scope for this element and its descendants.

<dashed-ident>

Specifies the name of an existing named timeline (i.e., declared using scroll-timeline-name or view-timeline-name) defined on a descendant element. This increases the timeline scope to the current element and to any of its descendants.

Description

The timeline-scope property modifies the scope of a named animation timeline. By default, a named timeline (i.e., declared using scroll-timeline-name or view-timeline-name) can only be set as the controlling timeline of a direct descendant element (i.e., by setting animation-timeline on it with the timeline name as its value). This is the default "scope" for the timeline.

The value of the timeline-scope is the name of a timeline defined on a descendant element; this changes the scope of the timeline to include the targeted element and its descendants. In other words, that element on which the timeline-scope property is defined, and all of its descendant elements, can be controlled using that timeline.

If no timeline (or more than one timeline) exists with the name given for the timeline-scope value, an inactive timeline with the specified name is created. The timeline-scope property only works with named timelines, and therefore can not be used in conjunction with anonymous timelines created using the view() or scroll() animation timeline functions.

Formal definition

Formal syntax

timeline-scope = 
  none             |
  all              |
  <dashed-ident>#  

Examples

In this example, we animated an element in response to the scrolling of another element by increasing the timeline scope with the timeline-scope property.

HTML

The HTML includes an element to animate and an element to scroll:

<div class="content">
  <div class="box animation"></div>
</div>

<div class="scroller">
  <div class="long-element"></div>
</div>

CSS

A scroll timeline named --my-scroller is defined using the scroll-timeline-name property on a scrolling element. This scroll timeline name is used in two other places: it is applied as the animation-timeline on the element we want to animate, and as timeline-scope on an ancestor of both the scroller and the animated element, increasing the scope.

We set the <body>'s height to 100vh, and lay its two child elements out as two equal columns using flexbox. To increase the timeline scope from the <div class="scroller"> element to the whole <body>, we set timeline-scope: --my-scroller on it. By doing so, the --my-scroller timeline can be set as the controlling timeline for an animation set on the <body> or any element nested inside it.

body {
  margin: 0;
  height: 100vh;
  display: flex;

  timeline-scope: --my-scroller;
}

.content,
.scroller {
  flex: 1;
}

We set --my-scroller as the scroll-timeline-name on the scrolling element that should provide the scroll progress timeline for our animated element. We add overflow to enable scrolling, adding a background color to make its boundary visible. We set a large height on the contents of our scrolling element so the element actually scrolls.

.scroller {
  overflow: scroll;
  scroll-timeline-name: --my-scroller;
  background: deeppink;
}

.long-element {
  height: 2000px;
}

Next, we give the animated element some rudimentary styles and apply an animation to it using the animation shorthand property. We set the animation-timeline to the named scroll timeline: --my-scroller. To reiterate, animating the element based on the scroll progress of it's cousin element is only possible because we set timeline-scope on a mutual ancestor; the animated element is not a descendant of the scrolling element.

.box {
  width: 100px;
  height: 100px;
  border-radius: 10px;
  background-color: rebeccapurple;
}

.animation {
  animation: rotate-appear 1ms linear;
  animation-timeline: --my-scroller;
}

@keyframes rotate-appear {
  from {
    rotate: 0deg;
    translate: 0;
  }

  to {
    rotate: 720deg;
    translate: 100%;
  }
}

@layer supports {
  @supports not (timeline-scope: none) {
    body::before {
      content: "Your browser does not support the 'timeline-scope' property.";
      background-color: wheat;
      display: block;
      text-align: center;
      padding: 1rem;
    }
  }
}

Result

Scroll the vertical bar on the pink area to see the square animate.

The key point to note here is that the animated element is not a descendant of the scrolling element — to make this work, we increase the scope of the --my-scroller timeline by setting timeline-scope: --my-scroller on the <body>.

Specifications

Browser compatibility

See also

• animation-timeline
• scroll-timeline, scroll-timeline-name
• view-timeline, view-timeline-name
• CSS scroll-driven animations