1. Web
  2. CSS
  3. Reference
  4. Values
  5. <animation-action>
View on MDN

<animation-action>

The <animation-action> enumerated data type is a CSS identifier that specifies how a triggered animation should behave when its trigger is activated and deactivated.

The <animation-action> keyword values are used in the following properties:

Syntax

Valid <animation-action> values:

none

The animation will not play.

play

The animation will play.

play-forwards

The animation will play. play-forwards differs from the play value in that it extends the effect of an animation-fill-mode set on the corresponding animation to before/after the trigger is activated/deactivated. The animation will play and adopt the animation's finished state once finished, if its animation-fill-mode is set to forwards or both.

play-backwards

The animation will play in reverse. Like play-forwards, it extends the effect of an animation-fill-mode set on the corresponding animation to before/after the trigger is activated/deactivated. The animation will play in reverse and adopt the animation's starting state once finished. It is important to note that, even if the animation-iteration-count is set to infinite, the animation will not play backwards a greater number of times than it has already played forwards. For example, if the animation has previously played forwards five times before the play-backwards behavior starts, it will then play backwards five times and stop.

play-once

The animation will play once and then stop.

pause

The animation will pause.

replay

The animation will play from the start (progress 0), regardless of where it had played to previously.

reset

The animation will pause, and its progress will be set back to 0.

Description

When setting an animation-trigger value on an animated element to specify the animation as a triggered animation, the value can include one or two <animation-action> values, separated by a space. The first value specifies the behavior of the animation when its trigger activates, while the optional second value specifies the behavior of the animation when its trigger deactivates.

If only a single value is specified, the animation doesn't change its behavior when its trigger deactivates; it will continue with the activation behavior. It has the same effect as setting none as the second value.

Some <animation-action> values are designed to be used together. For example:

  • play-forwards play-backwards is very common when you want a UI element to "animate in" when it appears on-screen, and then "animate out" again when it goes off-screen.
  • play pause is common for animating an element as it appears, then pausing the animation as it starts to go off-screen.

Other values are designed to be used on their own, for example play-once.

Formal syntax

<animation-action> = 
  none            |
  pause           |
  play            |
  play-backwards  |
  play-forwards   |
  play-once       |
  replay          |
  reset

Examples

Basic usage

In this example, we show how to create a basic scroll-triggered animation that plays forwards on trigger activation and backwards on trigger deactivation.

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.

html
<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 once. 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 on activation, and play in reverse on deactivation.

The .trigger <div> element creates the animated <div>'s trigger using a timeline-trigger value of --t view(). This value includes the identifier referenced in the animated <div>'s animation-trigger property value (the timeline-trigger-name), associating the two together. It also includes:

  • 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 value of contain, which means that the trigger will activate when the .trigger <div> is fully inside the viewport, and deactivate when it stops being fully inside the viewport.
css
div.animated {
  animation: rotate 1.5s infinite linear both;
  animation-trigger: --t play-forwards play-backwards;
}

div.trigger {
  timeline-trigger: --t view() contain;
}

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.

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

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

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

  to {
    rotate: 360deg;
  }
}

Result

The rendered result looks like this:

Try scrolling the content up. When the tracked <div> fully appears in the viewport, the animation will play; when it starts to leave the viewport at either edge, the animation will play in reverse.

Demonstrating different <animation-action> effects

In this example we show a series of <div> elements with the same scroll-triggered rotate animation applied as in the previous example, but different <animation-action> values. This allows you to compare and contrast the effect of the different actions.

HTML

We include a <section> element containing five <div> elements, each with a number inside. We also include some text content to cause the page to scroll, which we've hidden for brevity.

html
<section>
  <div class="one">1</div>
  <div class="two">2</div>
  <div class="three">3</div>
  <div class="four">4</div>
  <div class="five">5</div>
</section>

CSS

We set the same animation on each <div> element — we play the rotate animation an infinite number of times, with each iteration lasting two seconds. We also style each <div> to be a 50px diameter colored circle.

css
div {
  animation: rotate 2s infinite linear both;
  height: 50px;
  width: 50px;
  border: 5px solid black;
  border-radius: 50%;
  background-color: orange;
}

Next, we set the <section> element to create an animation trigger, with a timeline-trigger value of --t view() contain 20% contain 80%. There is nothing unusual going on here, except that we've set a timeline-trigger-activation-range value to contain 20% contain 80%. This means that the trigger will activate when the <section> element has scrolled around 20% of the way up the viewport, and deactivate when it has scrolled around 80% of the way up the viewport. This allows you to see the <animation-action> effects more clearly than if the activation range covered the entire viewport.

css
section {
  timeline-trigger: --t view() contain 20% contain 80%;
}

Next, we set a different animation-trigger property value on each <div> element. Each one references the <section> element's timeline-trigger-name, but each one has a different set of <animation-action> values applied. The last <div> additionally has a new animation property value applied, overriding the one we set earlier. It is the same as the original animation property, except that the iteration count is set to 1 rather than infinite. We have done this because it is easier to demonstrate the effect of play-once when the iteration-count is not infinite (if this is the case, it will play forever, regardless).

css
.one {
  animation-trigger: --t play-forwards play-backwards;
}

.two {
  animation-trigger: --t play;
}

.three {
  animation-trigger: --t play replay;
}

.four {
  animation-trigger: --t pause play;
}

.five {
  animation: rotate 2s 1 linear both;
  animation-trigger: --t play-once reset;
}

Result

The rendered result looks like this:

Scroll down to the point where the <section> and <div> elements enter the viewport. Move them through the start and end of the trigger activation range, concentrating on a different <div> each time, to visualize the effects of each set of <animation-action>s.

The effects are:

  1. The first <div> (far left) has play-forwards play-backwards set. When the tracked element enters the activation range, the animation starts to play forwards. When it leaves the activation range (at the top or bottom of the viewport), it will start to play backwards.
  2. The second <div> has a single <animation-action> set — play. When the tracked element enters the activation range, the animation starts to play. However, given that there is no deactivation action set to change its behavior, the animation continues to play forever until the page reloads.
  3. The third <div> has play replay set. When the tracked element enters the activation range, the animation starts to play forwards. When it leaves the activation range, the animation resets to progress 0, and then starts to play again.
  4. The fourth <div> has pause play set. When the tracked element enters the activation range, the animation continues to not play, as it is set to a paused state. However, when it leaves the activation range, the animation starts to play. From then on, the animation will pause when the tracked element is inside the activation range, and play when it is outside it.
  5. The fifth <div> (far right, with an iteration count of 1) has play-once reset set. When the tracked element enters the activation range, the animation plays once. When it leaves the activation range, the animation resets to progress 0 and pauses. From then on, the animation will play once whenever the tracked element enters the activation range, and reset when the tracked element leaves the activation range.

Specifications

Specification
CSS Animations Level 2
# animation-trigger-prop

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