timeline-trigger-source CSS property

Syntax

/* Keyword */
timeline-trigger-source: none;
timeline-trigger-source: auto;

/* Named timeline */
timeline-trigger-source: --my-timeline;

/* Anonymous scroll progress timeline */
timeline-trigger-source: scroll();
timeline-trigger-source: scroll(x root);

/* Anonymous view progress timeline */
timeline-trigger-source: view();
timeline-trigger-source: view(inline);
timeline-trigger-source: view(x 200px auto);

/* Multiple source values */
timeline-trigger-source: view(), none, --my-timeline;

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

The timeline-trigger-source property may be specified as one or more single animation timelines, separated by commas. Each animation timeline is specified using a none or auto keyword, a <dashed-ident>, a scroll() function, or a view() function.

Values

none

The element does not create a scroll-triggered animation trigger, as it has no timeline.

auto

The element does not create a scroll-triggered animation trigger, as its timeline is set to the document's default time-based timeline.

<dashed-ident>

The element creates a scroll-triggered animation trigger as a named view progress timeline.

scroll()

The element creates a scroll-triggered animation trigger as a anonymous scroll progress timeline.

view()

The element creates a scroll-triggered animation trigger as a anonymous view progress timeline.

Description

The timeline-trigger-source property specifies the timeline trigger that will control a scroll-triggered animation.

For example:

.trigger {
  timeline-trigger-name: --my-trigger;
  timeline-trigger-source: view();
}

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 creates an anonymous view progress timeline to control triggering animations.

The resulting ViewTimeline tracks the position of the .trigger element across the block-axis of the nearest ancestor scroller. The trigger is activated and deactivated when the tracked element is scrolled to certain positions inside the scrollport. By default, activation occurs when the tracked element starts to enter the viewport, and deactivation occurs when the tracked element completely exits the viewport.

An animated element can be triggered by the previously-described trigger by referencing its timeline-trigger-name in its animation-trigger property:

For example:

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

The <animation-action> keywords specified in the animation-trigger — play-forwards play-backwards — specify that the animation should play forwards when its trigger activates and backwards when its trigger deactivates.

Different source types

The timeline-trigger-source property can take one of three main value types:

• A view() function referencing an anonymous view progress timeline trigger. This is the nearest scrolling ancestor of the element that creates the trigger. As described previously, this allows you to create functionality whereby an element will start animating when it (or another element) reaches a certain scroll offset in the viewport, and stop animating (or some other action) when it (or another element) reaches a different scroll offset.
• A scroll() function referencing an anonymous scroll progress timeline trigger. This can be the root element or nearest scroller of the element that creates the trigger, or the element itself. This allows you to create functionality whereby an element will start animating when it (or another element) reaches an absolute scroll offset relative to the scrollport (not the viewport), and stop animation (or some other action) when it (or another element) reaches a different position in the scrollport.
• A <dashed-ident> referencing a named view- or scroll-progress timeline. This references a view-timeline-name or scroll-timeline-name set on the trigger.

Scroll progress timelines are arguably not as useful for scroll-triggered animations as view progress timelines. You are more likely to want an animation to start at an scroll offset relative to the viewport, not the entire scrollport, where the animation may well trigger off screen on smaller screens.

Setting the trigger's activation and active range

By default, the trigger's activation range is cover, which means that the trigger activates when the start edge of the tracked element enters the end edge of the viewport. A custom activation range can be set via the timeline-trigger-activation-range property.

The trigger's default active range is the same as the activation range (therefore cover, if the activation range is not set to a different range), which means that the trigger deactivates when the end edge of the tracked element has exited either edge of the viewport. A custom active range can be set via the timeline-trigger-active-range property.

Multiple sources

When multiple timeline values are specified in a single timeline-trigger-source 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-source value is set, the timeline-trigger-source will apply to all the timeline-trigger-names. If two timeline-trigger-source values are set, they will cycle between the timeline-trigger-names until all of them have a timeline-trigger-source value set. And so on.

For example, consider these declarations:

timeline-trigger-name: --my-trigger, --my-other-trigger, --another-trigger;
timeline-trigger-source: view(), --my-source;

In this case, the first name will use the view() source, and the second name will use the --my-source source. The third name will cycle back to using the view() source again.

Formal definition

Formal syntax

timeline-trigger-source = 
  <single-animation-timeline>#  

<single-animation-timeline> = 
  auto            |
  none            |
  <dashed-ident>  |
  <scroll()>      |
  <view()>        

<scroll()> = 
  scroll( [ <scroller> || <axis> ]? )  

<view()> = 
  view( [ <axis> || <'view-timeline-inset'> ]? )  

<scroller> = 
  root     |
  nearest  |
  self     

<axis> = 
  block   |
  inline  |
  x       |
  y       

<view-timeline-inset> = 
  [ [ auto | <length-percentage> ]{1,2} ]#  

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

Examples

Basic view progress timeline source usage

In this example, we show how to create a basic scroll-triggered animation that uses an anonymous view progress timeline trigger source.

HTML

Our markup contains two <div> elements, plus 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>

...

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

<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 timeline-trigger-name of --t; we also specify two <animation-action> values — play and pause — which specify that the animation will play when its trigger activates, and pause when it deactivates.

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

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

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

@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();
}

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 up. When any part of the .trigger <div> appears in the viewport, the animation will play; when it has completely left the viewport at either edge, the animation will pause.

Basic scroll progress timeline source usage

This example is nearly identical to the previous one, except that this time we are setting the timeline-trigger-source to equal an anonymous scroll progress timeline instead of an anonymous view progress timeline.

The HTML and CSS are nearly identical, except that this time we have set our .trigger <div> element's timeline-trigger-source to scroll() instead of view(). This creates the trigger as an anonymous scroll progress timeline on the nearest scrolling ancestor of the element.

We have also set a timeline-trigger-activation-range of 600px, which means that the trigger will activate (meaning the animation will start playing) when the tracked element scrolls upwards by 600px. If we didn't set this, the trigger would activate immediately on page load.

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

div.trigger {
  timeline-trigger-name: --t;
  timeline-trigger-source: scroll();
  timeline-trigger-activation-range: 600px;
}

Result

The rendered result looks like this:

The animation will start when the tracked element scrolls 600px upwards.

Specifications

Browser compatibility

See also

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