CSS mask-position Property

What You’ll Learn

The mask-position property defines where a mask-image is placed inside an element — using the same keywords, percentages, and lengths as background-position.

Introduction

The mask-position property in CSS defines the position of a mask image within an element. Masking allows you to hide or reveal specific parts of an element based on the transparency and position of the mask image.

This property is especially useful for creating complex shapes, patterns, and visual effects by positioning the mask precisely. Pair it with mask-image, mask-size, and mask-repeat for full control.

Definition and Usage

Use mask-position: center to center a silhouette mask, top left for corner placement, or percentages and pixels for fine-tuned offsets. The syntax mirrors background-position, so if you know one, the other feels familiar.

📝 Syntax

The syntax for the mask-position property is similar to background-position. It accepts horizontal and vertical position values:

element {
  mask-position: x-position y-position;
}

• x-position — specifies the horizontal position of the mask image.
• y-position — specifies the vertical position of the mask image.

Basic Example

.masked {
  width: 300px;
  height: 200px;
  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-position: center;
  mask-position: center;
}

Syntax Rules

• The initial value is 0% 0% (top-left corner).
• mask-position only applies when a mask-image is set.
• Keywords include top, left, bottom, right, and center.
• Length units like px and em, and percentages, are also supported.
• Include -webkit-mask-position alongside mask-position for broader Safari support.

💎 Property Values

The mask-position property accepts keywords, lengths, and percentages — the same value types as background-position.

🎯 Default Value

The default value of the mask-position property is 0% 0%, which places the mask image at the top-left corner of the element.

Common Position Values

Examples Gallery

Position a mask image at the center, in corners, with percentages, and compare multiple placement values side by side.

<style>
  .masked {
    width: 300px;
    height: 200px;
    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-position: center;
    mask-position: center;
  }
</style>

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

<style>
  .mask-corner {
    width: 280px;
    height: 200px;
    background: linear-gradient(135deg, #6366f1, #8b5cf6);
    -webkit-mask-image: url('/images/apple.png');
    mask-image: url('/images/apple.png');
    -webkit-mask-size: 80px;
    mask-size: 80px;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-position: top left;
    mask-position: top left;
  }
</style>

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

<style>
  .mask-percent {
    width: 280px;
    height: 200px;
    background: url('/images/valley-pattern.jpg') center/cover;
    -webkit-mask-image: url('/images/apple.png');
    mask-image: url('/images/apple.png');
    -webkit-mask-size: 70px;
    mask-size: 70px;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-position: 75% 25%;
    mask-position: 75% 25%;
  }
</style>

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

.mask-box {
  width: 200px;
  height: 140px;
  background: linear-gradient(135deg, #f97316, #ec4899);
  -webkit-mask-image: url('/images/apple.png');
  mask-image: url('/images/apple.png');
  -webkit-mask-size: 56px;
  mask-size: 56px;
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
}
.pos-center { mask-position: center; }
.pos-top-left { mask-position: top left; }
.pos-bottom-right { mask-position: bottom right; }

♿ Accessibility

• Set mask-image first — mask-position 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 different sizes — Pair mask-position with mask-size to see how placement changes at various dimensions.
• Check contrast — Partially masked areas can reduce readability if text sits over them.
• Offer fallbacks — Ensure content remains usable when masking is unsupported.

mask-position vs background-position

💡 Best Practices