CSS mask-origin Property

What You’ll Learn

The mask-origin property defines the positioning area for a mask-image — similar to how background-origin works for backgrounds.

Introduction

The mask-origin property in CSS defines the origin of the mask image used on an element. It determines the positioning area for the mask — similar to the background-origin property for background images.

This property is particularly useful when you want to control how the mask image is applied to an element’s content box, padding box, or border box. Pair it with mask-image, mask-size, and mask-position for precise mask placement.

Definition and Usage

Use mask-origin: border-box (the default) when the mask should align with the outer edge including the border. Use padding-box to start positioning inside the border, or content-box when the mask should align only with the inner content area.

📝 Syntax

The syntax for the mask-origin property uses one of three box-model keyword values:

element {
  mask-origin: value;
}

Here, value can be one of the specified keywords: border-box, padding-box, or content-box.

Basic Example

.masked-element {
  width: 300px;
  height: 200px;
  padding: 20px;
  border: 10px solid #334155;
  background: url('/images/valley-pattern.jpg') center/cover;
  -webkit-mask-image: url('/images/apple.png');
  mask-image: url('/images/apple.png');
  -webkit-mask-size: contain;
  mask-size: contain;
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-origin: padding-box;
  mask-origin: padding-box;
}

Syntax Rules

• The initial value is border-box.
• mask-origin only applies when a mask-image is set.
• border-box includes the border area in the positioning reference.
• padding-box starts positioning at the outer edge of the padding (inside the border).
• Include -webkit-mask-origin alongside mask-origin for broader Safari support.

💎 Property Values

The mask-origin property accepts three box-model keyword values that define the mask positioning area.

🎯 Default Value

The default value of the mask-origin property is border-box, which means the mask image is positioned relative to the border box of the element by default.

Positioning Areas

Examples Gallery

Apply a mask image and use mask-origin to control where the mask positioning area begins — then compare all three box values side by side.

<style>
  .masked-element {
    width: 280px;
    height: 200px;
    padding: 20px;
    border: 10px solid #334155;
    background: url('/images/valley-pattern.jpg') center/cover;
    -webkit-mask-image: url('/images/apple.png');
    mask-image: url('/images/apple.png');
    -webkit-mask-size: contain;
    mask-size: contain;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-origin: padding-box;
    mask-origin: padding-box;
  }
</style>

<div class="masked-element"></div>

<style>
  .mask-border {
    width: 280px;
    height: 200px;
    padding: 20px;
    border: 10px solid #334155;
    background: url('/images/valley-pattern.jpg') center/cover;
    -webkit-mask-image: url('/images/apple.png');
    mask-image: url('/images/apple.png');
    -webkit-mask-size: contain;
    mask-size: contain;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-origin: border-box;
    mask-origin: border-box;
  }
</style>

<div class="mask-border"></div>

<style>
  .mask-content {
    width: 280px;
    height: 200px;
    padding: 20px;
    border: 10px solid #334155;
    background: url('/images/valley-pattern.jpg') center/cover;
    -webkit-mask-image: url('/images/apple.png');
    mask-image: url('/images/apple.png');
    -webkit-mask-size: contain;
    mask-size: contain;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-origin: content-box;
    mask-origin: content-box;
  }
</style>

<div class="mask-content"></div>

.mask-box {
  padding: 20px;
  border: 10px solid #334155;
  -webkit-mask-image: url('/images/apple.png');
  mask-image: url('/images/apple.png');
  -webkit-mask-size: 60px;
  mask-size: 60px;
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-position: top left;
  mask-position: top left;
}
.origin-border { mask-origin: border-box; }
.origin-padding { mask-origin: padding-box; }
.origin-content { mask-origin: content-box; }

♿ Accessibility

• Set mask-image first — mask-origin has no effect without an active mask layer.
• Do not hide essential content — Masked-away text or controls may be invisible but still exist in the DOM.
• Test with visible padding — Add border and padding to see how each origin value shifts the mask.
• Check contrast — Partially masked areas can reduce readability if text sits over them.
• Offer fallbacks — Ensure content remains usable when masking is unsupported.

mask-origin vs background-origin

💡 Best Practices