animation-composition CSS property

Syntax

/* Single animation */
animation-composition: replace;
animation-composition: add;
animation-composition: accumulate;

/* Multiple animations */
animation-composition: replace, add;
animation-composition: add, accumulate;
animation-composition: replace, add, accumulate;

/* Global values */
animation-composition: inherit;
animation-composition: initial;
animation-composition: revert;
animation-composition: revert-layer;
animation-composition: unset;

Values

replace

The effect value overrides the underlying value of the property. This is the default value.

add

The effect value builds on the underlying value of the property. This operation produces an additive effect. For animation types where the addition operation is not commutative, the order of the operands is the underlying value followed by the effect value.

accumulate

The effect and underlying values are combined. For animation types where the addition operation is not commutative, the order of the operands is the underlying value followed by the effect value.

Description

Each property that is targeted by the @keyframes at-rule is associated with an effect stack. The value of the effect stack is calculated by combining the underlying value of a property in a CSS style rule with the effect value of that property in the keyframe. The animation-composition property helps to specify how to combine the underlying value with the effect value.

For example, in the CSS below, blur(5px) is the underlying value, and blur(10px) is the effect value. The animation-composition property specifies the operation to perform to produce the final effect value after compositing the effect of the underlying value and the effect value.

.icon:hover {
  filter: blur(5px);
  animation: 3s infinite pulse;
  animation-composition: add;
}

@keyframes pulse {
  0% {
    filter: blur(10px);
  }
  100% {
    filter: blur(20px);
  }
}

Consider different values for the animation-composition property in the above example. The final effect value in each of those cases will be calculated as explained below:

• With replace, blur(10px) will replace blur(5px) in the 0% keyframe. This is the default behavior of the property.
• With add, the composite effect value in the 0% keyframe will be blur(5px) blur(10px).
• With accumulate, the composite effect value in 0% keyframe will be blur(15px).

Formal definition

Formal syntax

animation-composition = 
  <single-animation-composition>#  

<single-animation-composition> = 
  replace     |
  add         |
  accumulate  

Examples

Understanding the animation-composition values

The example below shows the effect of different animation-composition values side-by-side.

HTML

<div class="container">
  replace
  <div id="replace" class="target"></div>
</div>
<div class="container">
  add
  <div id="add" class="target"></div>
</div>
<div class="container">
  accumulate
  <div id="accumulate" class="target"></div>
</div>

CSS

Here the underlying value is translateX(50px) rotate(45deg).

.container {
  width: 230px;
  height: 200px;
  background: cyan;
  display: inline-block;
  text-align: center;
}

.target {
  width: 20px;
  height: 50px;
  background: green;
  border-radius: 10px;
  margin: 20px 0;
}

@keyframes slide {
  20%,
  40% {
    transform: translateX(100px);
    background: yellow;
  }
  80%,
  100% {
    transform: translateX(150px);
    background: orange;
  }
}

.target {
  transform: translateX(30px) rotate(45deg);
  animation: slide 5s linear infinite;
}
.target:hover {
  animation-play-state: paused;
}
#replace {
  animation-composition: replace;
}
#add {
  animation-composition: add;
}
#accumulate {
  animation-composition: accumulate;
}

Result

• With replace, the final effect value for the transform property in the 20%, 40% keyframe is translateX(100px) (completely replacing the underlying value translateX(30px) rotate(45deg)). In this case, the element rotates from 45deg to 0deg as it animates from the default value set on the element itself to the non-rotated value set at the 20% mark. This is the default behavior.
• With add, the final effect value for the transform property in the 20%, 40% keyframe is translateX(30px) rotate(45deg) translateX(100px). So the element is first moved 100px to the right, rotated 45deg around the origin, then moved to the right by 30px.
• With accumulate, the final effect value in the 20%, 40% keyframe is translateX(130px) rotate(45deg). This means that the two X-axis translation values of 30px and 100px are combined or "accumulated".

Specifications

Browser compatibility

See also

• Using CSS animations
• Composite property of KeyFrameEffect
• Other related animation properties: animation, animation-delay, animation-direction, animation-duration, animation-fill-mode, animation-iteration-count, animation-name, animation-play-state, animation-timeline, animation-timing-function