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
/* none 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;
The timeline-trigger-name property may be specified using the keyword none, or one or more <dashed-ident> values separated by commas.
Values
none-
Specifies that the element does not define any scroll-triggered animation triggers.
<dashed-ident>-
An identifier for the trigger.
Description
The timeline-trigger-name property specifies one or more identifying names for a CSS scroll-triggered animation trigger.
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:
.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.
Note:
The timeline-trigger-name property can also be set via the timeline-trigger shorthand property.
Note: It is possible for the animated element and the element that creates the trigger to be the same element.
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. For example, this might 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:
.trigger {
timeline-trigger-name: --animation-trigger-1, --animation-trigger-2;
timeline-trigger-source: view();
}
It is possible to specify the same <dashed-ident> on multiple different triggers — all triggers will then trigger any animations that reference that <dashed-ident> in their associated animation-trigger value. However, you can't specify the same <dashed-ident> multiple times in the same timeline-trigger-name list — in such a case, only the last instance will define a trigger — the preceding ones will have no effect.
Formal definition
| Initial value | none |
|---|---|
| Applies to | all elements |
| Inherited | no |
| Computed value | as specified |
| Animation type | Not animatable |
Formal syntax
timeline-trigger-name =
none |
<dashed-ident>#
Examples
Basic usage
In this example, we show how to create a basic scroll-triggered animation.
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>
...
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 on activation, and pause on deactivation.
The .trigger <div> element creates the animated <div>'s trigger using:
- A
timeline-trigger-namevalue of--t, which is equal to the identifier referenced in the animated<div>'sanimation-triggerproperty value, associating the two together. - A
timeline-trigger-sourcevalue ofview(), which sets the timeline trigger as a view progress timeline, and the element providing the timeline trigger as the nearest scrolling ancestor element.
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 tracked <div> appears in the viewport, the animation will play; when it has completely left the viewport at either edge, the animation will pause.
Making the animated element the trigger
In this example, we demonstrate how an animated element can also create its own trigger.
HTML
This time, our markup contains only a single <div> element, plus basic text content to cause the page to scroll. We have hidden all the markup for brevity.
CSS
The <div> element has an animation applied that smoothly inverts its colors. We set an animation-trigger value on it that references a timeline-trigger-name of --t; we also specify two <animation-action> values — play-forwards and play-backwards — which specify that the animation will play forwards on activation, and play in reverse on deactivation.
We then specify the following properties on the same <div>:
-
A
timeline-trigger-namevalue of--t, to specify that the<div>creates the trigger for its own animation. -
A
timeline-trigger-sourcevalue ofview(), 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-rangevalue ofcontain, which means that the trigger will activate when the tracked<div>is fully inside the viewport, and deactivate when it stops being fully inside the viewport.Note: This is in contrast to the default activation range,
cover, which would cause the trigger to activate when any part of the tracked<div>enters the viewport and deactivate only when it has fully left the viewport.
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;
}
Finally, we define the @keyframes for the invert-colors animation:
@keyframes invert-colors {
from {
background: orange;
color: black;
}
to {
background: black;
color: orange;
}
}
Result
The rendered result looks like this:
Try scrolling the content up. When the <div> fully appears in the viewport, its animation will play; when any part of the <div> leaves the viewport at either edge, the animation will play backwards.
Specifications
| Specification |
|---|
| CSS Animations Level 2 # timeline-trigger-name |