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

timeline-trigger-active-range-start CSS property

· 52CE 我爱测

The **`timeline-trigger-active-range-start`** CSS property specifies the start of a scroll-triggered animation trigger's active range.

The timeline-trigger-active-range-start CSS property specifies the start of a scroll-triggered animation trigger's active range.

Syntax

/* Keywords */
timeline-trigger-active-range-start: auto;
timeline-trigger-active-range-start: normal;

/* <length-percentage> */
timeline-trigger-active-range-start: 10%;
timeline-trigger-active-range-start: 50px;

/* Named timeline range */
timeline-trigger-active-range-start: contain;
timeline-trigger-active-range-start: exit;

/* Named timeline with <length-percentage> */
timeline-trigger-active-range-start: entry -5%;
timeline-trigger-active-range-start: contain 100px;

/* Multiple range start values */
timeline-trigger-active-range-start:
  contain -10px,
  entry 5%;

/* Global values */
timeline-trigger-active-range-start: inherit;
timeline-trigger-active-range-start: initial;
timeline-trigger-active-range-start: revert;
timeline-trigger-active-range-start: revert-layer;
timeline-trigger-active-range-start: unset;

Values

This property is specified as a comma-separated list of the following values:

  • auto
    • : Specifies the value of the timeline-trigger-activation-range-start property. This is the default value.
  • normal
  • length-percentage
    • : Specifies a length or percentage value measured from the beginning of the normal timeline. Percentages are relative to the length of the normal timeline range.
  • timeline-range-name
    • : Specifies the start, or 0%, of the cover, contain, entry, exit, entry-crossing, exit-crossing, or scroll timeline range.
  • <timeline-range-name> <length-percentage>
    • : Specifies a length or percentage value measured from the beginning of the specified named timeline range. Percentages are relative to the length of the named range.

Description

The timeline-trigger-active-range-start property can be used to explicitly set the start of a trigger's active range to a value equal to or preceding the timeline-trigger-activation-range-start, which specifies the start of the trigger's activation range.

The active range is the range in which a trigger remains activated once activation has occurred. Activation occurs when the tracked element enters the activation range, and deactivation occurs when it leaves the active range. By default, the active range starts where the activation range starts. This property creates a buffer zone and is used to prevent premature resetting when a user scrolls back and forth across the activation's starting point. Only when a tracked element moves out of the active range does the trigger become inactive.

The default value of timeline-trigger-active-range-start is auto, which sets the value to the same named range and offset as the timeline-trigger-activation-range-start. When specified as a timeline range, offset, or both, this property sets the start of the active range to a point that is independent of the timeline-trigger-activation-range-start value. If the range start position doesn't extend the activation range, it has no effect.

The value of normal sets the start of the active range to the start of the default named range, resolving to either cover 0% for a view progress timeline (the timeline-trigger-source is set to a view() function) or scroll 0% for a scroll progress timeline (the timeline-trigger-source is set to a scroll() function).

Other values of the timeline-trigger-active-range-start property can be used to set:

  • An offset from the normal range
    • : A <length> or <percentage> value specifies an offset from the beginning of the normal timeline of cover or scroll. Negative values outset the start, resulting in a longer active range. Positive values inset the start of the active range, making it shorter.
  • The start of a specific named range
    • : A <timeline-range-name> value specifies a 0% offset along the named timeline range, which is either cover, contain, entry, exit, entry-crossing, exit-crossing, or scroll. See Understanding timeline range names.
  • An offset from a specific named range
    • : When both a <timeline-range-name> and <length> or <percentage> value are specified, the start is offset by the distance specified from the start of the named range. Percentage values are relative to the range specified. See Setting insets using percentages.

The timeline-trigger-active-range-start property, along with the timeline-trigger-active-range-end property, can also be set using the timeline-trigger-active-range shorthand, which in turn can be set using the timeline-trigger shorthand.

Specifying multiple range start values

When you specify multiple comma-separated values in a single timeline-trigger-active-range-start declaration, they apply to the timeline triggers in the order in which they appear in the timeline-trigger-name property. When the number of triggers and timeline-trigger-active-range-start property values do not match, they are applied in the same way as multiple animation property values.

For example, if multiple timeline-trigger-name values are set, but only a single timeline-trigger-active-range-start value is set, the timeline-trigger-active-range-start will apply to all the timeline-trigger-names. If two or more timeline-trigger-active-range-start values are set, they will cycle between the timeline-trigger-names until every timeline trigger has a timeline-trigger-active-range-start value set.

Consider these declarations:

timeline-trigger-name: --my-trigger, --my-other-trigger, --another-trigger;
timeline-trigger-active-range-start:
  contain,
  entry 5%;

In this case, --my-trigger will use the contain range start and --my-other-trigger will use the entry 5% range start. As there are three names but only two range starts, the range starts are cycled, so the third trigger name, --another-trigger, will use the contain range start.

Formal definition

Formal syntax

Examples

Basic usage

This example demonstrates the effect of extending a trigger's active range. It compares two identical triggered animations, with the start of one animation trigger's active range outset using the timeline-trigger-active-range-start property.

HTML

The markup contains four div elements — two to animate and two to create a trigger on — plus some basic text content to cause the page to scroll. The text content is hidden for brevity.

<div class="animated">I am animated</div>
<div class="animated longer">I am animated longer</div>

...
<section>
  <div class="trigger">I create the trigger</div>
  <div class="trigger longer">I create a longer trigger</div>
</section>
...
<div class="animated">I am animated</div>
<div class="animated longer">I am animated longer</div>
<p>
  Fusce dictum ex quis ipsum consectetur placerat. Cras sed lectus ex. Quisque
  purus dolor, vulputate ac mi eget, commodo varius odio. Suspendisse faucibus
  ipsum vel libero finibus, in placerat nibh congue. Sed iaculis, metus et
  euismod posuere, mi diam vestibulum felis, ac vulputate eros ipsum id justo.
  Etiam a tincidunt purus. Maecenas semper sed enim at blandit. Aenean ut
  sagittis lorem, eget gravida purus. Phasellus eleifend, lectus nec pulvinar
  facilisis, dui dolor feugiat odio, iaculis tempor felis est non tortor. In
  suscipit lorem efficitur molestie tempus. Integer sit amet neque et risus
  iaculis sodales sed eget diam. Quisque sodales nunc sapien, vitae lacinia ex
  luctus quis. Maecenas scelerisque scelerisque elit eu consequat. Etiam ac
  tristique tellus, sed tincidunt velit.
</p>

<p>
  Fusce dictum ex quis ipsum consectetur placerat. Cras sed lectus ex. Quisque
  purus dolor, vulputate ac mi eget, commodo varius odio. Suspendisse faucibus
  ipsum vel libero finibus, in placerat nibh congue. Sed iaculis, metus et
  euismod posuere, mi diam vestibulum felis, ac vulputate eros ipsum id justo.
  Etiam a tincidunt purus. Maecenas semper sed enim at blandit. Aenean ut
  sagittis lorem, eget gravida purus. Phasellus eleifend, lectus nec pulvinar
  facilisis, dui dolor feugiat odio, iaculis tempor felis est non tortor. In
  suscipit lorem efficitur molestie tempus. Integer sit amet neque et risus
  iaculis sodales sed eget diam. Quisque sodales nunc sapien, vitae lacinia ex
  luctus quis. Maecenas scelerisque scelerisque elit eu consequat. Etiam ac
  tristique tellus, sed tincidunt velit.
</p>

<section>
  <div class="trigger">I create the trigger</div>
  <div class="trigger longer">I create a longer trigger</div>
</section>
<p>
  Fusce dictum ex quis ipsum consectetur placerat. Cras sed lectus ex. Quisque
  purus dolor, vulputate ac mi eget, commodo varius odio. Suspendisse faucibus
  ipsum vel libero finibus, in placerat nibh congue. Sed iaculis, metus et
  euismod posuere, mi diam vestibulum felis, ac vulputate eros ipsum id justo.
  Etiam a tincidunt purus. Maecenas semper sed enim at blandit. Aenean ut
  sagittis lorem, eget gravida purus. Phasellus eleifend, lectus nec pulvinar
  facilisis, dui dolor feugiat odio, iaculis tempor felis est non tortor. In
  suscipit lorem efficitur molestie tempus. Integer sit amet neque et risus
  iaculis sodales sed eget diam. Quisque sodales nunc sapien, vitae lacinia ex
  luctus quis. Maecenas scelerisque scelerisque elit eu consequat. Etiam ac
  tristique tellus, sed tincidunt velit.
</p>

<p>
  Fusce dictum ex quis ipsum consectetur placerat. Cras sed lectus ex. Quisque
  purus dolor, vulputate ac mi eget, commodo varius odio. Suspendisse faucibus
  ipsum vel libero finibus, in placerat nibh congue. Sed iaculis, metus et
  euismod posuere, mi diam vestibulum felis, ac vulputate eros ipsum id justo.
  Etiam a tincidunt purus. Maecenas semper sed enim at blandit. Aenean ut
  sagittis lorem, eget gravida purus. Phasellus eleifend, lectus nec pulvinar
  facilisis, dui dolor feugiat odio, iaculis tempor felis est non tortor. In
  suscipit lorem efficitur molestie tempus. Integer sit amet neque et risus
  iaculis sodales sed eget diam. Quisque sodales nunc sapien, vitae lacinia ex
  luctus quis. Maecenas scelerisque scelerisque elit eu consequat. Etiam ac
  tristique tellus, sed tincidunt velit.
</p>

CSS

The .animated elements' position is set to fixed, positioning them near the top-left of the scrollport to enable us to see when their animations start and stop.

body {
  width: 80%;
  margin: 0 auto;
  font-family: "Helvetica", "Arial";
  font-size: 1.3rem;
}

div {
  height: 100px;
  border: 5px solid black;
}

.animated {
  width: 100px;
  background: orange;
}

.trigger {
  background: wheat;
}
.animated {
  position: fixed;
  top: 25px;
  left: 25px;
}
.animated.longer {
  left: 150px;
}
section {
  display: flex;
  gap: 20px;
}

Next, we define the @keyframes for a rotate animation:

@keyframes rotate {
  from {
    rotate: 0deg;
  }

  to {
    rotate: 360deg;
  }
}

Using the animation shorthand, the rotate animation is applied to the .animated elements. Without an associated trigger, the elements would start animating when the page loads. The animation-trigger property makes it a triggered animation. The values reference a timeline-trigger-name of --t and --longer-t, respectively, and define the same two <animation-action> values — play and pause — which specify that the animations will play on activation and pause on deactivation.

.animated {
  animation: rotate 3s infinite linear;
  animation-trigger: --t play pause;
}
.animated.longer {
  animation-trigger: --longer-t play pause;
}

The .trigger element creates the .animated element's trigger via the following properties:

  • A timeline-trigger-name with value --t, which is equal to the identifier referenced in the .animated element's animation-trigger property value, associating the two together.
  • A timeline-trigger-source with value view(), which sets the timeline trigger as a view progress timeline, and the element providing the timeline trigger as the nearest scrolling ancestor element.
  • A timeline-trigger-activation-range of contain 50% contain 100%. The contain range spans from when the trigger element has completely entered the scrollport to when it starts to leave. This value sets the trigger's activation range to start at 50% through the contain range (when the tracked element's bottom edge is halfway through the scrollport), and end at 100%, when the element's top edge first exits the scrollport.

The .trigger.longer element creates the .animated.longer element's trigger via the following properties:

  • A timeline-trigger-name with value --longer-t (overriding the --t), which is equal to the identifier referenced in the .animated.longer element's animation-trigger property value, associating the two together.

  • A timeline-trigger-active-range-start of contain 0%, which occurs when the trigger's bottom edge is at the bottom edge of the scrollport.

.trigger {
  timeline-trigger-name: --t;
  timeline-trigger-source: view();
  timeline-trigger-activation-range: contain 50% contain 100%;
}
.trigger.longer {
  timeline-trigger-name: --longer-t;
  timeline-trigger-active-range-start: contain 0%;
}
@supports not (timeline-trigger-active-range-start: contain 0%) {
  body::before {
    content: "Your browser does not support the timeline-trigger-active-range-start property.";
    background-color: wheat;
    text-align: center;
    padding: 1rem 0;

    z-index: 1;
    position: fixed;
    inset: 40% 0 auto;
  }
}

Result

basic-example

Try scrolling the content up. Both animations start playing when the tracked .trigger elements get to the middle of the scrollport and stop playing when they start to leave the top edge of the scrollport.

If you then scroll downward, both animations start playing when they are fully in the scrollport, with the top edge of the tracked elements meeting the top edge of the scrollport. The first animation pauses when the tracked element exits the activation range, when it passes the center of the scrollport. The second animation doesn't pause until its trigger element starts to leave the scrollport at its bottom edge. This is because the active range on the second animation extends how long the trigger remains active.

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

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

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