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

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

/* Range start value only */
/* Single value */
timeline-trigger-active-range: 0%;
timeline-trigger-active-range: 0px;
timeline-trigger-active-range: cover;
/* Two values */
timeline-trigger-active-range: exit 10%;
timeline-trigger-active-range: contain 50px;

/* Range start and end values */
/* Two values */
timeline-trigger-active-range: 5% 95%;
timeline-trigger-active-range: entry exit;
timeline-trigger-active-range: auto 10%;
timeline-trigger-active-range: 10% normal;
/* Three values */
timeline-trigger-active-range: contain contain 90%;
timeline-trigger-active-range: 200px exit 600px;
timeline-trigger-active-range: entry 10% 90%;
/* Four values */
timeline-trigger-active-range: entry 0% exit 50%;
timeline-trigger-active-range: contain 100px contain 90%;

/* Multiple ranges */
timeline-trigger-active-range:
  cover,
  entry 0% 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;

The timeline-trigger-active-range shorthand property is specified as one or more single animation ranges, separated by commas. Each animation range is specified as a timeline-trigger-active-range-start value, and optionally, a timeline-trigger-active-range-end value.

Each longhand property value is specified as one of:

• A <timeline-range-name> value.
• A <length-percentage> value.
• The keyword normal.
• The keyword auto.
• A <timeline-range-name> followed by a <length-percentage> value.

Values

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

The keyword normal, the keyword auto, a <length-percentage>, a <timeline-range-name>, or a <timeline-range-name> <length-percentage> pair, 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> <length-percentage> pair, representing the timeline-trigger-active-range-end. If a <timeline-range-name> is set without a <length-percentage>, the <length-percentage> defaults to 100%.

Description

The timeline-trigger-active-range property can be used to set a custom active range for a CSS scroll-triggered animation trigger. The active range is the range within which the trigger will stay active it has been activated.

This is useful in situations where you want an animation to be triggered in a small activation range, but then you want the trigger to stay active within a larger range. The trigger will only deactivate when the tracked element leaves the active range.

The active range's default value is auto, which sets the active range to the same as the activation range. The activation range's default value is cover. This means that the trigger activates when the start edge of the tracked element enters the end edge of the viewport, and deactivates when the end edge of the tracked element has exited either edge of the viewport. The trigger will also stay active over this same range.

The ranges can be changed by setting different timeline-trigger-activation-range and timeline-trigger-active-range values.

For example:

.trigger {
  timeline-trigger-name: --my-trigger;
  timeline-trigger-source: view();
  timeline-trigger-activation-range: entry;
  timeline-trigger-active-range: cover;
}

An element with these declarations set will create a trigger with an identifying timeline-trigger-name of --my-trigger, and a timeline-trigger-source value of view(), which sets the timeline tracking the element to a view progress timeline based on its nearest scrolling ancestor element.

We also set a timeline-trigger-activation-range value of entry and a timeline-trigger-active-range of cover. This means that the trigger will activate when the tracked element enters the entry range — the range between which its start edge and end edge scroll into the viewport. However, once activated, the trigger will stay active as long as the tracked element stays inside the cover range — the trigger will only deactivate again once the tracked element has completely left the viewport.

An animated element can be triggered by the previously-described trigger by referencing the trigger's identifying name in its animation-trigger property.

For example:

.animated {
  animation: rotate 3s infinite linear both;
  animation-trigger: --my-trigger play-forwards play-backwards;
}

In this case, the animation will be triggered by the trigger with the timeline-trigger-name of --my-trigger. Its <animation-action> keywords — play-forwards play-backwards — specify that the animation should play forwards when the trigger activats, and backwards when it deactivates.

timeline-trigger-active-range value explanation

In terms of explicit and default values, timeline-trigger-active-range works in a very similar way to the animation-range property. In this section we will provide a brief explanation and then link to the appropriate sections on that page for more details.

If two values are specified as components of the timeline-trigger-active-range property, they will be interpreted in the order timeline-trigger-active-range-start then timeline-trigger-active-range-end.

The value of each component can be one of the following:

• The keyword normal, which is equivalent to 0% for start and 100% for end.
• A <length-percentage>, which sets a specific length or percentage through the default cover range.
• A <timeline-range-name>, which sets a different timeline range with an implicit percentage of 0% for start and 100% for end.
• A <timeline-range-name> followed by a <length-percentage>, which sets a specific percentage through a different timeline range. These values are space-separated.

See Explicitly defining both range start and range end with two values for more information.

When defining a timeline-trigger-active-range-start value explicitly and letting the timeline-trigger-active-range-end value adopt a default value, what the default value is depends on the supplied start value, and the rules to determine this are complex. Read Defining range start and defaulting range end for more details.

Specifying multiple ranges

When multiple ranges are specified in a single timeline-trigger-active-range property, they are distributed between the specified timeline-trigger-name values in the same fashion as multiple animation values are distributed (see Setting multiple animation property values).

If multiple timeline-trigger-name values are set, but only a single timeline-trigger-active-range value is set, the timeline-trigger-active-range will apply to all the timeline-trigger-names. If two timeline-trigger-active-range values are set, they will cycle between the timeline-trigger-names until all of them have a timeline-trigger-active-range value set. And so on.

For example, consider these declarations:

timeline-trigger-name: --my-trigger, --my-other-trigger, --another-trigger;
timeline-trigger-active-range: cover, contain;

In this case, the first name will use the cover range, and the second name will use the contain range. The third name will cycle back to using the cover range again.

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

Active range demonstration

In this example, we demonstrate the effect of defining a timeline-trigger-active-range on a trigger.

HTML

Our markup contains two <div> elements, an <input type="checkbox"> that we will use to toggle the active range on and off, and some basic text content to cause the page to scroll.

We have hidden the text content for brevity.

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

...

<div class="trigger">I create the trigger</div>

<form>
  <label for="active-checkbox">Deactivate active range?</label>
  <input type="checkbox" checked id="active-checkbox" />
</form>

...

<div class="animated">I am animated</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>

<div class="trigger">I create the trigger</div>

<form>
  <label for="active-checkbox">Deactivate active range?</label>
  <input type="checkbox" checked id="active-checkbox" />
</form>

<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 <div> element has an animation applied that rotates it. We set an animation-trigger value on it that references a trigger name of --t; we also specify two <animation-action> values — play and pause — which specify that the animation will play on activation, and pause on deactivation.

The .trigger <div> element creates the animated <div>'s trigger using:

• A timeline-trigger-name value of --t, which is equal to the identifier referenced in the animated <div>'s animation-trigger property value, associating the two together.
• A timeline-trigger-source value of 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 entry — on its own, this means that the trigger will activate when the tracked element starts to enter the viewport and deactivate when the tracked element has completely entered the viewport.

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;
}

form {
  position: fixed;
  padding: 5px;
  background: white;
  border: 2px solid black;
  bottom: 0;
  right: 0;
}

@supports not (timeline-trigger-name: --t) {
  body::before {
    font-family: sans-serif;
    font-size: 1.3rem;
    content: "Your browser does not support scroll-triggered animations.";
    background-color: wheat;
    position: fixed;
    left: 0;
    right: 0;
    top: 40%;
    text-align: center;
    padding: 1rem 0;
    z-index: 1;
  }
}

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

div.trigger {
  timeline-trigger-name: --t;
  timeline-trigger-source: view();
  timeline-trigger-activation-range: entry;
}

Now we use a combination of the :has() and :checked pseudo-classes to select the tracked element only when the checkbox is checked. The <form> element appears right after the .trigger <div> as a direct sibling, hence using the + combinator in the selector that we are checking for. The result is that when the checkbox is unchecked, the trigger deactivates as soon as the tracked element leaves the entry range, but when it is checked (as it is by default), the timeline-trigger-active-range property is applied, and the trigger won't deactivate until the tracked element leaves the cover range.

div.trigger:has(+ form input:checked) {
  timeline-trigger-active-range: cover;
}

Next, we give the animated <div> a position of fixed, positioning it near the top-left of the viewport so that we can easily see when its animation starts and stops.

div.animated {
  position: fixed;
  top: 25px;
  left: 25px;
}

Finally, we define the @keyframes for the rotate animation:

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

  to {
    rotate: 360deg;
  }
}

Result

The rendered result looks like this:

Try scrolling the content. Initially the rotation will start when the tracked <div> enters the viewport, but won't stop until the tracked <div> has completely exited the viewport again. Now uncheck the checkbox and try scrolling the content again. Without the active range set, the rotation will start when the tracked <div> enters the viewport and then stop as soon as it has completely entered the viewport.

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 animations module