Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / CSS

mask-size — sizing mask images

The mask-size property sets the dimensions of mask-layer images, not the element itself. It accepts lengths, percentages, auto, contain, and cover, with separate sizes available for multiple layers.

Version: CSS modules; structured CSSWG indexes reconciled with pinned MDN BCD; Chromium 152 scope gate, per-example verification still required

Syntax

mask-size: <bg-size>#;
<bg-size> = [ <length-percentage [0,∞]> | auto ]{1,2} | cover | contain;

mask-size scales images supplied by mask-image without changing the element’s layout dimensions. Its initial value is auto, and it is not inherited. It does not create a mask by itself.

One length or percentage specifies the width, with the height defaulting to auto; two values specify width and height respectively. Negative values are invalid. Percentages refer to the corresponding dimensions of the mask positioning area, determined by mask-origin, not the image file’s dimensions.

auto uses the image’s natural dimensions and aspect ratio where available. A gradient without natural dimensions fills the positioning area with auto auto. contain preserves the aspect ratio and fits the entire image inside that area; cover preserves the aspect ratio and covers the whole area, so part of the image may extend beyond it. Two explicit dimensions can distort the aspect ratio.

Separate sizes for multiple layers with commas, following the order of mask-image. A short list repeats, while excess values are ignored. mask-repeat separately controls image tiling. Important exception: when the source is an SVG mask element, mask-size has no effect on that layer; that element defines its geometry.

Examples

<!doctype html>
<meta charset="utf-8">
<title>mask-size</title>
<style>
  body { margin: 20px; background: white; }
  .sample {
    width: 240px;
    height: 120px;
    background: #0066cc;
    mask-image: linear-gradient(black, black);
    mask-mode: alpha;
    mask-origin: border-box;
    mask-size: 50% 100%;
    mask-position: center;
    mask-repeat: no-repeat;
  }
</style>
<div class="sample"></div>

Result

A 120 × 120 CSS-pixel blue square is visible, centered horizontally within a 240 × 120 CSS-pixel element; the remaining area shows the white page background.

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources