📦 Mastering mask-origin in CSS

📌 What Is mask-origin?

The mask-origin property controls which box (border-box, padding-box, or content-box) is used as the reference area for positioning and sizing a mask image.
In simple terms:mask-origin decides where your mask is applied inside the element.

>>“mask-origin defines the box your mask belongs to — border, padding, or content.”

🧩 Basic Syntax

Syntax

mask-origin: border-box | padding-box | content-box;

🎯 Understanding Each Value

ValueReference AreaEffect on Mask
border-boxIncludes border + padding + contentMask covers the whole element box
padding-boxIncludes padding + contentMask starts inside the border
content-boxOnly content areaMask clipped to content only

Note

mask-origin works together withmask-position, mask-size, and mask-clip.

🧪 Example: border-box (Default)

border-box

.box {
  mask-image: url(shape.png);
  mask-origin: border-box;
  mask-size: cover;
}

✔ Mask covers entire element including border area.

🧪 Example: padding-box

padding-box

.inner-mask {
  padding: 20px;
  mask-image: url(mask.png);
  mask-origin: padding-box;
}

✔ Mask begins inside the border
✔ Useful when border should appear outside the mask shape

🧪 Example: content-box

content-box

.content-only {
  padding: 20px;
  mask-image: url(mask.png);
  mask-origin: content-box;
}

✔ Mask is applied only to the content area
✔ Great for masking text or inner content without affecting padding/border

🌈 Visual Comparison

mask-origin valueMask Area Affected
border-boxMask covers border → padding → content
padding-boxMask covers padding → content
content-boxMask only covers actual content

🎨 mask-origin + mask-position

Position inside origin box

.highlight {
  mask-image: url(circle.svg);
  mask-origin: content-box;
  mask-position: center;
}

✔ Mask is centered only within the content area, not the full element box.

🔥 Advanced Example: mask-origin + mask-clip

mask-origin + mask-clip

.clip-demo {
  mask-image: url(shape.png);
  mask-origin: padding-box;
  mask-clip: content-box;
}

✔ Mask starts at padding-box
✔ But is clipped to content-box
✔ Produces precise mask regions

🧠 Using Multiple Masks with mask-origin

Multiple masks

.multi {
  mask-image: url(mask1.png), url(mask2.png);
  mask-origin: border-box, content-box;
}

✔ Each mask uses its own origin
✔ Allows complex multi-layer masking layouts

🛠️ Best Practices

  • Use border-box when mask should fill entire element
  • Use padding-box when mask should ignore borders
  • Use content-box when masking only main content
  • Pair with mask-size and mask-position for best control
  • Test across browsers for consistent rendering

⚠️ Browser Support

  • ✔ Chrome
  • ✔ Safari
  • ✔ Edge
  • ⚠️ Firefox requires -webkit-mask-origin

Note

Include both mask-origin and -webkit-mask-origin for maximum compatibility.

🔍 Debugging Tips

  • If mask seems misaligned → check if origin box is correct
  • If mask appears clipped → inspect mask-clip settings
  • Try changing mask-size to visualize how it scales inside the origin box
  • Use DevTools to inspect element box model

🔗 Helpful Resources

>>“mask-origin gives you pixel-perfect control over where your mask artwork begins.” 🎭✨