CSS mask-size Property

What You’ll Learn

The mask-size property defines how large a mask-image is drawn — using the same keywords and lengths as background-size.

Introduction

The mask-size property in CSS defines the size of an element’s mask image. Masks hide or reveal parts of an element using an image or graphical representation.

By setting the mask size, you control how the image fits the element and how it affects the visibility of the underlying content. Pair it with mask-image, mask-repeat, and mask-position for full control.

Definition and Usage

Use mask-size: cover to fill the element with the mask, contain to show the full shape without clipping, or pixel and percentage values for precise dimensions. The syntax mirrors background-size, so if you know one, the other feels familiar.

📝 Syntax

The syntax for the mask-size property accepts one or two values for width and height:

element {
  mask-size: value;
}

Basic Example

.masked-element {
  width: 300px;
  height: 300px;
  background: url('/images/valley-pattern.jpg') center/cover;
  -webkit-mask-image: url('/images/apple.png');
  mask-image: url('/images/apple.png');
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-size: cover;
  mask-size: cover;
}

Syntax Rules

• The initial value is auto (intrinsic mask image size).
• mask-size only applies when a mask-image is set.
• Keywords include cover, contain, and auto.
• Length units like px and percentages set explicit width and height.
• Include -webkit-mask-size alongside mask-size for broader Safari support.

💎 Property Values

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

🎯 Default Value

The default value of the mask-size property is auto, which means the mask image is displayed at its intrinsic size or scaled to fit the element, depending on the mask-repeat property.

Common Size Values

Examples Gallery

Scale a mask to cover the element, fit inside without clipping, use fixed pixels, and compare multiple size values side by side.

<style>
  .masked-element {
    width: 300px;
    height: 300px;
    background: url('/images/valley-pattern.jpg') center/cover;
    -webkit-mask-image: url('/images/apple.png');
    mask-image: url('/images/apple.png');
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-size: cover;
    mask-size: cover;
  }
</style>

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

<style>
  .mask-contain {
    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-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-position: center;
    mask-position: center;
    -webkit-mask-size: contain;
    mask-size: contain;
  }
</style>

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

<style>
  .mask-fixed {
    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-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-position: center;
    mask-position: center;
    -webkit-mask-size: 80px;
    mask-size: 80px;
  }
</style>

<div class="mask-fixed"></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-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-position: center;
  mask-position: center;
}
.sz-cover { mask-size: cover; }
.sz-contain { mask-size: contain; }
.sz-fixed { mask-size: 48px; }

♿ Accessibility

• Set mask-image first — mask-size 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 cover vs contain — Compare both values to see clipping vs full-shape visibility.
• Check contrast — Partially masked areas can reduce readability if text sits over them.
• Offer fallbacks — Ensure content remains usable when masking is unsupported.

mask-size vs background-size

💡 Best Practices