大网数据广告活动
Web 标准与前端开发

`timeline-scope` CSS property

· 52CE 我爱测

The **`timeline-scope`** CSS property modifies the scope of a named animation timeline.

The timeline-scope CSS property modifies the scope of a named animation timeline.

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

This property is specified as a keyword or a comma-separated list of custom timeline names:

  • none
    • : Applies no change to the timeline scope. This is the default.
  • all
    • : Sets the scope so that any timeline names set on the element or in its subtree are matched only by elements within the same subtree.
  • <dashed-ident>
    • : Specifies one or more comma-separated timeline names that are declared using scroll-timeline-name or view-timeline-name. Sets the scope so that when the specified scroll-timeline-name or view-timeline-name values are set on the element or in its subtree, they are matched only by elements within the same subtree.

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 cannot be used in conjunction with anonymous timelines created using the animation-timeline/view or animation-timeline/scroll animation timeline functions.

Formal definition

Formal syntax

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 its 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.

Examples

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

来源:MDN Web Docs / Mozilla 贡献者 · 作者与贡献记录 · CC BY-SA 2.5。离线整理了版式、链接和媒体显示。

资料来源与适用范围

资料来源
MDN Web Docs / Mozilla 贡献者
适用范围
请按文中版本与环境说明核对
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY-SA 2.5

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。