CSS Portal

CSS animation-composition Property

If this site has been useful, we’d love your support! Consider buying us a coffee to keep things going strong!

Description

The animation-composition property defines how multiple animations affecting the same CSS property are combined when they run at the same time. Instead of one animation simply overriding another, this property controls how their effects interact, making it possible to layer animations in a more intentional and predictable way. This is especially useful when building complex UI motion, where separate animations may control different aspects of movement, timing, or emphasis but still need to coexist without visual conflict.

Traditionally, when multiple animations targeted the same property, the result could feel limiting or unpredictable, as later animations would often override earlier ones. With animation-composition, each animation can contribute to the final computed value in a controlled manner. This allows designers and developers to think in terms of animation layers, where effects can build upon one another rather than compete. For example, a base animation might define a subtle motion, while another adds emphasis or interaction feedback, all without rewriting or duplicating logic. This makes animation systems more modular and easier to maintain over time.

The property works alongside other animation-related features, such as animation-name, which determines which animations are applied, and animation-timing-function, which defines how those animations progress over time. While those properties control what plays and how it moves, animation-composition governs how multiple animations blend together. This separation of concerns makes it easier to reason about animation behavior, especially in large projects or component-based design systems.

In practice, animation-composition is particularly valuable for modern interfaces that rely on layered motion - such as hover effects combined with attention cues or state transitions. Instead of rewriting animations or carefully timing them to avoid clashes, developers can define clear composition rules that ensure smooth and intentional motion. This leads to cleaner code, better reusability, and more expressive animations that feel cohesive rather than chaotic.

Definition

Initial value
replace
Applies to
all elements
Inherited
no
Computed value
as specified
Animatable
no
JavaScript syntax
object.style.animationComposition

Syntax

animation-delay: replace | add | accumulate

Values

  • replaceThe effect value overrides the underlying value of the property. This is the default value.
  • addThe 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.
  • accumulateThe 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.

Example

<div class="examples">
<div class="example">
<h3>Add composition</h3>
<div class="box combined"></div>
</div>
<div class="example">
<h3>Replace composition</h3>
<div class="box replaced"></div>
</div>
</div>
/* Layout */
body {
    font-family: system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial;
    display: flex;
    align-items: center;
    justify-content: center;
    height: 100vh;
    margin: 0;
    background: #f7f7fb;
    color: #111;
}

.examples {
    display: flex;
    gap: 48px;
    align-items: center;
}

.example {
    text-align: center;
}

h3 {
    margin: 0 0 12px;
    font-size: 15px;
    color: #333;
}

/* Box styling */
.box {
    width: 100px;
    height: 100px;
    border-radius: 12px;
    background: linear-gradient(135deg, #ff9a9e, #fad0c4);
    margin: 0 auto;
    display: inline-block;
    transform-origin: center;
}

/* Keyframes */
@keyframes moveX {
    from { transform: translateX(0); }
    to   { transform: translateX(120px); }
}

@keyframes spin {
    from { transform: rotate(0deg); }
    to   { transform: rotate(360deg); }
}

/* Demonstration of animation-composition */
/* When both animations use 'add', their transform lists accumulate (translation + rotation).
   When set to 'replace', later animations replace the transform value from earlier animations. */

.combined {
    /* First animation: moveX, Second: spin */
    animation: moveX 2s infinite alternate ease-in-out, spin 2s infinite linear;
    animation-composition: add, add;
}

.replaced {
    animation: moveX 2s infinite alternate ease-in-out, spin 2s infinite linear;
    animation-composition: replace, replace;
}

Browser Support

The following information will show you the current browser support for the CSS animation-composition property. Hover over a browser icon to see the version that first introduced support for this CSS property.

This property is supported in some modern browsers, but not all.
Desktop
Chrome
Edge
Firefox
Opera
Safari
Tablets & Mobile
Chrome Android
Firefox Android
Opera Android
Safari iOS
Samsung Internet
Android WebView
-

Last updated by CSSPortal on: 1st January 2026

If this site has been useful, we’d love your support! Consider buying us a coffee to keep things going strong!