CSS mask-composite Property

Description

The mask-composite property controls how multiple mask layers are combined to form the final transparency map that is applied to an element. When you supply more than one mask (for example via the shorthand mask), each layer contributes an alpha map; mask-composite defines the compositing operation used to merge the alpha values of the top layer with the accumulated result of the layers beneath it. Conceptually, think of each mask layer as a grayscale image that is merged per-pixel with prior layers to produce a single mask that ultimately gates the element’s painting.

At the pixel level, the property operates on alpha information rather than color: it decides how opacity values combine (for example whether areas from a new mask add to, remove from, or intersect with existing opaque regions). The compositing is carried out in the mask space before that mask is applied to the element’s rendering, and it is applied consistently across mask images, gradients, and SVG masks (for mask sources such as mask-image). Because the operations work on the mask’s transparency, color channels of mask images are disregarded unless the mask mode forces them into use; the end result is a single alpha map used to clip or reveal the underlying painting.

In practice, mask-composite is often used in combination with layered masks and other clipping or blending techniques to create complex reveals, cutouts, or boolean-like masking effects. It interacts conceptually with clipping mechanisms (for example clip-path) and with compositing/blending at the painting level (for example mix-blend-mode), but it only governs how the mask layers themselves merge — it does not change the geometric layout of the element. Because mask compositing can require intermediate rasterization and offscreen compositing, it can have performance implications (especially when animated), and the visual/interactive behavior of masked areas (hit-testing, accessibility affordances) can vary by user agent, since masking affects painting rather than layout geometry.

Definition

Initial value: add
Applies to: all elements; In SVG, it applies to container elements excluding the <defs> element and all graphics elements
Inherited: no
Computed value: as specified
Animatable: yes
JavaScript syntax: object.style.maskComposite

Syntax

mask-composite: <value>;

Values

<value>
1. add – The mask layers are combined in a way that shows the union of all masks.
2. subtract – The top mask subtracts from the bottom mask, making the overlapped area transparent.
3. intersect – Only the intersection of mask layers is visible; areas outside the overlap are hidden.
4. exclude – The areas where mask layers overlap are excluded (made transparent), while the non-overlapping areas are visible.
5. replace – Only the topmost mask layer is applied, completely replacing any lower masks.
6. inherit – The element inherits the mask-composite value from its parent.
7. initial – Sets the property to its default value (which is usually add).
8. unset – Resets the property to either its inherited value or initial value if no parent exists.

Example

HTML

<div class='container'>

  <h1>CSS mask-composite demo</h1>

  <p class='note'>Two circular mask layers are combined using different mask-composite modes.</p>



  <div class='grid'>

    <figure class='card add'>

      <figcaption>add</figcaption>

    </figure>



    <figure class='card subtract'>

      <figcaption>subtract</figcaption>

    </figure>



    <figure class='card intersect'>

      <figcaption>intersect</figcaption>

    </figure>



    <figure class='card exclude'>

      <figcaption>exclude</figcaption>

    </figure>

  </div>

</div>

CSS

/* Layout */
* { box-sizing: border-box; }
body { margin: 0; font-family: system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial; background: #0b1020; color: #e6eef8; padding: 28px; }
.container { max-width: 800px; }
h1 { margin: 0 0 8px 0; font-size: 20px; }
.note { margin: 0 0 18px 0; color: #9fb0cc; font-size: 13px; }
.grid { display: grid; grid-template-columns: repeat(4, 160px); gap: 18px; }
figure { margin: 0; display: flex; align-items: center; justify-content: center; border-radius: 12px; position: relative; height: 160px; }
figcaption { position: absolute; bottom: 10px; left: 12px; font-weight: 700; font-size: 13px; text-transform: lowercase; color: rgba(255,255,255,0.92); text-shadow: 0 1px 0 rgba(0,0,0,0.45); }

/* Background artwork for masked elements */
.card {
  background-image: linear-gradient(135deg, #ff7a7a 0%, #ffd97a 40%, #7afcff 100%);
  box-shadow: 0 6px 18px rgba(2,8,23,0.6), inset 0 -8px 30px rgba(255,255,255,0.02);
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-position: center;
  mask-position: center;
  -webkit-mask-size: cover;
  mask-size: cover;
}

/* Define two circular mask layers (left and right circles). Black = visible, transparent = cut-out. */
:root {
  --two-circles: radial-gradient(circle at 30% 50%, black 40%, transparent 41%),
                 radial-gradient(circle at 70% 50%, black 40%, transparent 41%);
}

/* Default mask-image applied to every card */
.card { -webkit-mask-image: var(--two-circles); mask-image: var(--two-circles); }

/* Different composite modes for the second mask layer (composed over the previous result) */
.add {
  /* combine masks by adding; result shows both circles */
  -webkit-mask-composite: add; /* WebKit-prefixed (historical) */
  mask-composite: add;
}

.subtract {
  /* subtract the second circle from the first */
  -webkit-mask-composite: subtract;
  mask-composite: subtract;
}

.intersect {
  /* keep only the overlap between the two circles */
  -webkit-mask-composite: intersect;
  mask-composite: intersect;
}

.exclude {
  /* exclude the overlapping area (xor-like) */
  /* WebKit historically used 'xor' for this mode */
  -webkit-mask-composite: xor;
  mask-composite: exclude;
}

/* Small responsiveness */
@media (max-width: 720px) {
  .grid { grid-template-columns: repeat(2, 1fr); gap: 12px; }
  figure { height: 140px; }
}

Result

Editor

Browser Support

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