Day 109: the animation-composition property

posted on 21.08.2024

It’s time to get me up to speed with modern CSS. There’s so much new in CSS that I know too little about. To change that I’ve started #100DaysOfMoreOrLessModernCSS. Why more or less modern CSS? Because some topics will be about cutting-edge features, while other stuff has been around for quite a while already, but I just have little to no experience with it.

CSS animations can be composited in three ways: replace, add, and accumulate. The animation-composition property allows you to switch between them.

div {
  animation: changeColor 1s forwards;
  animation-composition: add;
}

Let's say you have two color HEX values, #112233 and #224466. Here's what happens with each composition type when you animate the background color of an element from the first to the second color.

replace: The background color changes from the first to the second color. In other words, the second color replaces the first color.
Result: #224466
add: The second color is added to the first color, creating a new color.
Result: #336699
accumulate: The first and second colors are combined. Often this yields the same result as add.
Result: #336699

:root {
  --color-a: #112233;
  --color-b: #224466;
}

button {
  background-color: var(--color-a);
  animation: changeColor 2s forwards;
}

@keyframes changeColor {
  to {
    background-color: var(--color-b);
  }
}

button {
  /* default */
  /* animation-composition: replace; */
}

button.add {
  animation-composition: add;
}

butotn.accumulate {
  animation-composition: accumulate;
}

Each button starts with #112233. The first button turns into #224466, and the second and third buttons turn into #336699 (112233 + 224466).

Colors:

#112233

#224466

#336699

Click one of the following buttons to repeat the animation.

Bramus has a great non-technical explanation for the values. He says that you could compare this with a cup that is filled with tea. When pouring milk in it this would happen:

replace: The tea gets removed, and is replaced by the milk.
add: The milk gets added to the cup, but it remains layered on top of the tea.
accumulate: The milk is added to the tea and, because they are both fluids, they mix nicely.

“replace” is the default you’re familiar with. “add” makes sense, I guess. To understand the difference between “add” and “accumulate”, you have to animate multiple properties. To illustrate that, I’ll steal another great example from my friend Bramus.

In the CSS code, all three animations start with transform: translateX(50px) rotate(45deg) and end with transform: translateX(100px).

.box {
  transform: translateX(50px) rotate(45deg);

  transform-origin: 50% 50%;
  animation: adjust 5s linear infinite alternate;
}

@keyframes adjust {
  to {
    transform: translateX(100px);
  }
}

See the Pen CSS `animation-composition` by web.dev (@web-dot-dev) on CodePen.

Each composition type yields a different result:

replace: translateX(50px) rotate(45deg) is replaced by translateX(100px). The box moves from 50px to 100px and rotates back to 0deg.
add: translateX(50px) rotate(45deg) turns into translateX(50px) rotate(45deg) translateX(100px). The box moves 50px, rotates 45deg, and then moves 100px.
accumulate: translateX(50px) rotate(45deg) turns into translateX(150px) rotate(45deg). The 100px is added to the 50px, and the box moves from 50px to 150px and rotates 45deg.

You may think that the result of using add and accumulate should be the same because the box is moved by 150px on the x-axis in both cases but the order of transform functions matters. They are applied from left to right. With animation-composition: add, the box moves 50px, rotates, and then moves another 100px. With animation-composition: accumulate, it moves 150px and then rotates. If you're curious to learn why exactly the result is different in the end, I suggest you trying reading the transforms spec.

See on CodePen

Day 109: the animation-composition property

Further reading