🧩 Mastering mask-composite in CSS

📌 What Is mask-composite?

The mask-composite property controls how multiple mask layers combineto create a final masking shape.
When you apply more than one mask-image, they stack — and mask-compositedefines whether they intersect, subtract, add, or exclude each other.
This is similar to path operations in Illustrator or boolean operations in Figma. 🎨✨

>>“mask-composite defines the math of how multiple masks interact — overlap, cut out, add, or exclude.”

🧩 Basic Syntax

Syntax

mask-composite: add | subtract | intersect | exclude;

✔ Applies when you use multiple mask layers
✔ Each composite value applies between corresponding mask layers

🎯 What Each Value Means

Composite ModeDescription
addBoth mask shapes are combined (union)
subtractThe top mask subtracts from the mask beneath
intersectOnly the overlapping region is visible
excludeEverything except their overlap is visible (XOR)

Note

mask-composite only works for multiple masks (comma-separated mask-image values).

🧪 Example: Add (Union)

add example

.shape {
  mask-image: url(circle-mask.png), url(square-mask.png);
  mask-composite: add;
}

✔ The circle + square become one combined mask shape
✔ Great for merging shapes or creating organic blobs

🧪 Example: Subtract

subtract example

.cutout {
  mask-image: url(big-circle.png), url(small-circle.png);
  mask-composite: subtract;
}

✔ The small circle cuts a hole inside the big circle
✔ Perfect for donut/ring shapes or UI cutouts

🧪 Example: Intersect

intersect example

.intersection {
  mask-image: url(circle.png), url(triangle.png);
  mask-composite: intersect;
}

✔ Only the overlapping area is visible
✔ Useful for spotlight or focused reveal effects

🧪 Example: Exclude (XOR)

exclude example

.xor-mask {
  mask-image: url(mask1.png), url(mask2.png);
  mask-composite: exclude;
}

✔ Their overlapping region becomes transparent
✔ Great for artistic or glitch-style effects

🌈 Advanced Example: Multiple Composites

Multiple masks

.multi {
  mask-image: url(circle.png), url(rect.png), url(star.png);
  mask-composite: add, subtract;
}

✔ circle + rectangle → union
✔ result − star → cutout
✔ Enables complex stencil designs

🎨 Example: Creating a Donut Mask

Donut mask

.donut {
  mask-image: url(outer-circle.png), url(inner-circle.png);
  mask-size: contain;
  mask-repeat: no-repeat;
  mask-composite: subtract;
}


✔ Inner circle subtracts from outer → perfect ring shape

🔥 Example: Letter Cutout Mask

Text-cutout

.cut-text {
  mask-image: url(rect.png), url(text-mask.png);
  mask-composite: subtract;
}

✔ Text removes itself from the rectangle mask
✔ Creates a classic “text knockout” effect

⚠️ Vendor Prefixing

Firefox uses a different syntax:

Firefox composite

mask-composite: add;
-moz-mask-composite: add;

Note

For cross-browser support: ✔ Use both mask-composite and -moz-mask-composite.

🛠️ Best Practices

  • Use add to merge multiple shapes into one mask
  • Use subtract to create cutout shapes or donuts
  • Use intersect for spotlight or focused reveals
  • Use exclude for artistic and abstract mask effects
  • Always pair with mask-position and mask-size for precision

⚠️ Browser Support

  • ✔ Chrome
  • ✔ Safari
  • ✔ Edge
  • ⚠️ Firefox: requires -moz-mask-composite

Note

mask-composite is powerful but inconsistent across browsers — always test your designs.

🔍 Debugging Tips

  • Ensure mask images have transparency or proper alpha channels
  • If results look inverted, swap mask layer order
  • Use DevTools to inspect mask layers (Chrome supports mask debugging)
  • Start simple → add more layers gradually

🔗 Helpful Resources

>>“mask-composite unlocks true graphic design power in CSS — blend, subtract, merge, and sculpt shapes freely.” ✨