Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท Filters, Masks and Shapes

The mask-composite property

Reference for the CSS mask-composite property: combine several mask layers with add, subtract, intersect or exclude to cut complex shapes out of an element.

When an element has more than one mask layer, mask-composite decides how each layer is combined with the layers below it before the result is applied to the element. The default, add, simply stacks them, so anything covered by any layer is visible. The other operators let you subtract one shape from another, keep only the overlap, or keep everything except the overlap.

That makes it possible to cut holes, make crescents and rings, and build shapes from simple gradient circles without any SVG.

CSS
.crescent {
  mask-image: radial-gradient(circle at 35% 50%, #000 40px, transparent 41px),
              radial-gradient(circle at 65% 50%, #000 40px, transparent 41px);
  mask-composite: subtract;
}

Try it

The four operators on two circles

The first layer is the left circle, the second layer is the right circle. With subtract the left circle loses the part that overlaps the right one, leaving a crescent.

Syntax

CSS
mask-composite: <compositing-operator>#

/* <compositing-operator> = add | subtract | intersect | exclude */
  • Initial value: add
  • Applies to: all elements; in SVG, container elements (except <defs>) and graphics elements
  • Inherited: no
  • Animatable: no
  • Computed value: as specified

Values

Value Description
add The layer is placed over the layers below it. The result shows wherever either one is opaque.
subtract The layer is shown only where the layers below it are transparent. It is the layer minus what is beneath it.
intersect Only the area where both the layer and the layers below it are opaque is kept.
exclude Keeps areas covered by exactly one of the two; the overlap is removed.

Usage notes

  • The first layer is on top and the operator on a layer acts on the layers beneath. The operator on the last (bottom) layer has no effect, as there is nothing under it.
  • One value per layer. The list lines up with the mask-image list and repeats if it is shorter.
  • Layer order matters for subtract. Swapping the two gradients above gives the other crescent.
  • Rings and cut-outs. A big circle with subtract below a smaller one makes a ring. A rectangle with exclude and a circle cuts a hole.
  • Not the old prefixed keywords. The legacy -webkit-mask-composite property used different keywords (source-over, source-out, source-in, xor). If you must support old browsers, write both properties.
  • Alpha, not color. Compositing works on the mask's alpha (or luminance with mask-mode); the layer colors do not matter.

Browser support

The standard mask-composite keywords are in current versions of the major browsers; older WebKit and Blink versions only knew the prefixed property with different keywords, so check a compatibility table if you support them.