1. Web
  2. CSS
  3. Reference
  4. Properties
  5. timeline-trigger-name
View on MDN

timeline-trigger-name CSS property

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

The timeline-trigger-name CSS property specifies a scroll-triggered animation trigger's identifier(s).

Syntax

css
/* Keyword */
timeline-trigger-name: none;

/* Single dashed ident */
timeline-trigger-name: --my-trigger;
timeline-trigger-name: --my-other-trigger;

/* Multiple dashed idents */
timeline-trigger-name: --my-trigger, --my-other-name;

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

Values

Specified as one or more <dashed-ident> values separated by commas, or the keyword none.

none

Specifies that the element does not define any scroll-triggered animation triggers.

<dashed-ident>

An identifier to name the trigger.

Description

The timeline-trigger-name property specifies one or more identifying names for a CSS scroll-triggered animation trigger. This identifier is used within the animation-trigger property value.

For example:

css
.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. The timeline-trigger-source declaration is needed to create a timeline to control triggering animations; in this case, the value of view() creates an anonymous view progress timeline.

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 specific positions inside the scrollport. By default, activation occurs when the tracked element starts to enter the scrollport, and deactivation occurs when the tracked element completely exits the scrollport.

Any animated element with its animation-trigger property set to --my-trigger will have its animation controlled by the --my-trigger trigger:

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

Each animation-trigger value includes two or three components: the <dashed-ident> identifying the trigger, and one or two <animation-action> keywords specifying what should happen when the trigger is activated and, optionally, when it's deactivated. In this case, the animation will play once when activated.

It is possible for the animated element and the element that creates the trigger to be the same element. In this case, the animated element creates its own trigger:

css
.animatedAndTrigger {
  animation: rotate 3s infinite linear both;
  animation-trigger: --my-trigger play-once;

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

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

Multiple trigger names

You can specify multiple, comma-separated <dashed-ident> values in the same trigger's timeline-trigger-name value, meaning that it can be referenced by multiple identifiers. This can be useful in a situation where you have multiple components dropped into a page that you want to trigger animations on, but which use predefined animation-trigger values that you can't edit.

You could use multiple timeline-trigger-name values to create a trigger for all the animations:

css
.trigger {
  timeline-trigger-name: --animation-trigger-1, --animation-trigger-2;
  timeline-trigger-source: view();
}

If you specify the same <dashed-ident> multiple times in the same timeline-trigger-name list, only the last instance will define a trigger. The preceding ones will have no effect.

If multiple elements define triggers with the same trigger name, the trigger defined by the last element in the source order is used, unless scoped. See trigger-scope for more details.

Formal definition

Initial valuenone
Applies toall elements
Inheritedno
Computed valueas specified
Animation typeNot animatable

Formal syntax

timeline-trigger-name = 
  none             |
  <dashed-ident>#

Examples

Basic usage

In this example, we create a basic scroll-triggered animation.

HTML

Our markup contains two <div> elements, one to animate and one on which to create a trigger, plus some basic text content to cause the page to scroll. We have hidden the text content for brevity.

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

...

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

...

CSS

The animated <div> element's position is set to fixed, positioning it near the top-left of the scrollport to enable us to see when its animation starts and stops.

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

Next, we define the @keyframes for the rotate animation we will use later:

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

  to {
    rotate: 360deg;
  }
}

Using the animation shorthand, the .animated element has the rotate animation applied. Without an associated trigger, the element would start animating when the page loads. The animation-trigger property makes it a triggered animation. The value references a timeline-trigger-name of --t and specifies two <animation-action> values — play and pause — which specify that the animation will play on activation, and pause on deactivation.

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

The .trigger <div> element creates the animated <div>'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.
css
.trigger {
  timeline-trigger-name: --t;
  timeline-trigger-source: view();
}

Result

Try scrolling the content up. When any part of the tracked .trigger element appears in the scrollport, the animation plays; when it has completely left the scrollport at either edge, the animation pauses.

Making the animated element the trigger

This example demonstrates how an animated element can create its own trigger.

HTML

This time, our markup contains a single <div> element, plus basic text content to cause the page to scroll. We have hidden all the markup for brevity.

CSS

We first define a keyframe animation that inverts the foreground and background colors:

css
@keyframes invert-colors {
  from {
    background: orange;
    color: black;
  }

  to {
    background: black;
    color: orange;
  }
}

We set an animation-trigger value that references a timeline-trigger-name of --t. We also specify two <animation-action> values — play-forwards and play-backwards — which set the animation to play forwards on activation and in reverse on deactivation.

We then specify the following properties on the same <div>:

  • A timeline-trigger-name with value --t. This specifies that the <div> creates the trigger for its own animation.
  • A timeline-trigger-source with value view(). This 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 with value contain. This means that the trigger will activate when the tracked element is fully inside the scrollport, and deactivate when it stops being fully inside the scrollport. This is in contrast to the default activation range, cover, which would cause the trigger to activate when any part of the element enters the scrollport and deactivate only when it has fully left the scrollport. This would make the reverse animation occur when the element is out of view.
css
div {
  animation: invert-colors 0.6s ease-in both;

  animation-trigger: --t play-forwards play-backwards;

  timeline-trigger-name: --t;
  timeline-trigger-source: view();
  timeline-trigger-activation-range: contain;
}

Result

Try scrolling the content up. The tracked element's animation plays after it has fully entered the scrollport, and pauses when it starts to leave the scrollport.

Specifications

Specification
Animation Triggers
# propdef-timeline-trigger-name

Browser compatibility

See also

Help improve MDN

Learn how to contribute

This page was last modified on by MDN contributors.

View this page on GitHub • Report a problem with this content