timeline-trigger-active-range CSS property

Constituent properties

This property is a shorthand for the following CSS properties:

• timeline-trigger-active-range-start
• timeline-trigger-active-range-end

Syntax

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

/* Range start only */
/* Offset only */
timeline-trigger-active-range: 10%;
timeline-trigger-active-range: 40px;
/* Named timeline only */
timeline-trigger-active-range: cover;
/* Named timeline and offset value */
timeline-trigger-active-range: exit -10%;
timeline-trigger-active-range: contain 50px;

/* Range start and end */
timeline-trigger-active-range: entry exit;
/* Offset on start only */
timeline-trigger-active-range: 10% normal;
timeline-trigger-active-range: 100px contain;
timeline-trigger-active-range: entry 10% contain;
/* Offset on end only */
timeline-trigger-active-range: normal exit-crossing 90%;
timeline-trigger-active-range: auto 10%;
timeline-trigger-active-range: contain contain 90%;
/* Offset for both start and end */
timeline-trigger-active-range: 5% 95%;
timeline-trigger-active-range: 200px exit 600px;
timeline-trigger-active-range: entry 10% 90%;
/* Named timeline and offset for both start and end */
timeline-trigger-active-range: entry 0% exit 50%;
timeline-trigger-active-range: contain 100px contain 90%;

/* Multiple ranges */
timeline-trigger-active-range:
  cover,
  entry -5% exit 50%;

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

Values

This property is specified as a comma-separated list of animation ranges. Each animation range is specified as a timeline-trigger-active-range-start value, and, optionally, a timeline-trigger-active-range-end value.

<'timeline-trigger-active-range-start'>

The keyword normal, the keyword auto, a <length-percentage>, a <timeline-range-name>, or a <timeline-range-name> followed by a <length-percentage>, representing the timeline-trigger-active-range-start. If a <timeline-range-name> is set without a <length-percentage>, the <length-percentage> defaults to 0%.

<'timeline-trigger-active-range-end'>

The keyword normal, the keyword auto, a <length-percentage>, a <timeline-range-name>, or a <timeline-range-name> followed by a <length-percentage>, representing the timeline-trigger-active-range-end. If a <timeline-range-name> is set without a <length-percentage>, the <length-percentage> defaults to 100%.

Percentages are relative to the length of the named timeline range if one is specified, or the timeline represented by normal if not.

Description

The timeline-trigger-active-range property can be used to explicitly specify the start or both the start and end of a trigger's active range. The property sets both the timeline-trigger-active-range-start and timeline-trigger-active-range-end properties in one declaration, with each specified as a timeline range, offset, or both. Start and end offsets are both measured from the start of their ranges.

A trigger's active range is the range along the associated scrollport within which a CSS scroll-triggered animation trigger will stay active once activated. Activation occurs when the tracked element enters the activation range, and deactivation occurs when it leaves the active range. The default value is auto, which sets the timeline-trigger-active-range value to the same as the timeline-trigger-activation-range.

Making the active range longer than the activation range is useful when you want to trigger an animation in a small activation range, but you want the trigger to stay active within a larger range. The trigger will only deactivate when the tracked element leaves the active range.

A value of normal sets the active range to the default named range. The default named range depends on the timeline-trigger-source: it is equivalent to cover for a view progress timeline and scroll for a scroll progress timeline. The default offset values are 0% and 100%. Therefore, normal resolves to either cover 0% cover 100% or scroll 0% scroll 100%.

The timeline-trigger-active-range property can be used to set:

Start and end offsets from the normal range

A <length> or <percentage> value specifies an offset from the beginning of the normal timeline, which again defaults to cover for a view progress timeline source, and scroll for a scroll progress timeline source. Negative values outset the start and end, resulting in a longer active range. Positive values inset the start and end of the active range, making it shorter.

Specific named ranges

If a <timeline-range-name> value is set without including an offset, the offset defaults to 0% for start and 100% for the end values. The named timeline ranges include cover, contain, entry, exit, entry-crossing, exit-crossing, and scroll. See Understanding timeline range names.

Offsets from specific named ranges

When both a <timeline-range-name> and <length> or <percentage> value are specified, the start and end values are offset by the distances along the specified named ranges. Percentage values are relative to the range specified. See Setting insets using percentages.

In each component of a timeline-trigger-active-range value, the <timeline-range-name> value must come before the <length> or <percentage> offset. In the following example, you might think timeline-trigger-active-range-start is set to contain, and timeline-trigger-active-range-end is set to 50%, but this is not the case. Instead, timeline-trigger-active-range-start is set to contain 50% while timeline-trigger-active-range-end defaults to auto:

timeline-trigger-active-range: contain 50%;

To set timeline-trigger-active-range-start to contain and timeline-trigger-active-range-end to 50%, explicitly set 0%, which is the default start offset:

timeline-trigger-active-range: contain 0% 50%;

A set active range must be equal to or larger than the activation range. Specifically, the timeline-trigger-active-range-start value must come before or at the same position as the timeline-trigger-activation-range-start value, and the timeline-trigger-active-range-end value must be the same as or come after the timeline-trigger-activation-range-end value. If either value is within the activation range, the value will have no effect, and the active range will be equal to the activation range.

The timeline-trigger-active-range property, along with the timeline-trigger-name, timeline-trigger-source, and timeline-trigger-activation-range properties, can also be set using the timeline-trigger shorthand.

Explicit and default values of timeline-trigger-active-range

In terms of explicit and default values, timeline-trigger-active-range works in exactly the same way as the animation-range property. See the following for more information:

• Explicitly defining both range start and range end with two values
• Defining range start and defaulting range end

Specifying multiple ranges

When multiple values are specified in a comma-separated timeline-trigger-active-range declaration, each value applies to a timeline trigger in the order in which the names appear in the timeline-trigger-name property. When the number of triggers and timeline-trigger-active-range property values do not match, they are applied in the same way as multiple animation property values:

• If the number of timeline-trigger-active-range values exceeds the number of timeline-trigger-name values, the excess range values are discarded.
• If the number of trigger names is greater than the number of ranges, the timeline-trigger-active-range values are cycled until every timeline-trigger-name value has a timeline-trigger-active-range value set.
• If multiple timeline-trigger-name values are set, but only one timeline-trigger-active-range value is set, the timeline-trigger-active-range will apply to all the timeline-trigger-names.

Formal definition

Formal syntax

timeline-trigger-active-range = 
  [ <'timeline-trigger-active-range-start'> <'timeline-trigger-active-range-end'>? ]#  

<timeline-trigger-active-range-start> = 
  [ auto | normal | <length-percentage> | <timeline-range-name> <length-percentage>? ]#  

<timeline-trigger-active-range-end> = 
  [ auto | normal | <length-percentage> | <timeline-range-name> <length-percentage>? ]#  

<length-percentage> = 
  <length>      |
  <percentage>  

Examples

Basic usage

This example demonstrates the effect of extending a trigger's active range by comparing a triggered animation with a longer active range than its activation range against an identical triggered animation with no timeline-trigger-active-range property set.

HTML

The markup contains four <div> elements — two to animate and two to create a trigger on — plus some content that causes the page to scroll. We have hidden the extra content 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: Arial, Helvetica, sans-serif;
  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 --longerT, respectively, and define the same <animation-action> values on each — 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: --longerT 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 25% contain 75%. 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 25% of the way through the contain range and end 75% of the way through the range. In other words, the activation range is the middle half of the scrollport.

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

• A timeline-trigger-name with value --longerT (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 of cover 0% cover 100%. The cover range spans from when the trigger element starts to enter the scrollport to when it has completely left. In other words, the active range is when any part of the tracked element is in the scrollport.

.trigger {
  timeline-trigger-name: --t;
  timeline-trigger-source: view();
  timeline-trigger-activation-range: contain 25% contain 75%;
}
.trigger.longer {
  timeline-trigger-name: --longerT;
  timeline-trigger-active-range: cover 0% cover 100%;
}

@supports not (timeline-trigger-active-range: contain 0%) {
  body::before {
    content: "Your browser does not support the timeline-trigger-active-range property.";
    background-color: wheat;
    text-align: center;
    padding: 1rem 0;

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

Result

Try scrolling the content up. Both animations start playing when the tracked .trigger elements are about a quarter of the way up the scrollport. Continue scrolling. The first animation pauses when its trigger element gets to 75% through the scrollport, whereas the second animation doesn't pause until its trigger element has completely left the scrollport.

This is because the active range extends how long the trigger remains active, but doesn't change where activation occurs.

Specifications

Browser compatibility

See also

• timeline-trigger-active-range-end, timeline-trigger-active-range-start
• animation-trigger
• timeline-trigger-name, timeline-trigger-source, and timeline-trigger-activation-range
• timeline-trigger shorthand property
• trigger-scope
• <animation-action> type
• Using CSS scroll-triggered animations
• CSS animation triggers module
• CSS animations module