Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท Filters, Masks and Shapes

The mask-size property

Reference for the CSS mask-size property: scale a mask image with auto, cover, contain, lengths or percentages, with examples and usage notes.

The mask-size property scales each mask layer. Use contain to fit a whole shape inside the element, cover to fill it completely, or an explicit width and height for exact control. The default auto keeps the image's own size, which for a gradient means the full size of the positioning area.

It mirrors background-size. Together with mask-repeat it is how you turn an SVG icon into a mask that scales with its box.

CSS
.icon {
  mask-image: url(icon.svg);
  mask-repeat: no-repeat;
  mask-position: center;
  mask-size: contain;
}

Try it

Sizing a circular mask

A gradient has no natural proportions, so auto, contain and cover all give it the size of the area. The explicit sizes show the circle changing into smaller circles and ellipses.

Syntax

CSS
mask-size: <bg-size>#

/* <bg-size> = [ <length-percentage [0,โˆž]> | auto ]{1,2} | cover | contain */
  • Initial value: auto
  • Applies to: all elements; in SVG, container elements (except <defs>) and graphics elements
  • Inherited: no
  • Animatable: yes (as a repeatable list of lengths or percentages)
  • Computed value: as specified, but with lengths made absolute

Values

Value Description
auto Uses the image's intrinsic size or proportions. With two values, auto on one axis keeps the image's ratio.
<length> An exact size. One value sets the width and the height stays auto.
<percentage> A percentage of the mask positioning area.
cover Scales the image, keeping its ratio, to the smallest size that covers the whole area; parts may be cut off.
contain Scales the image, keeping its ratio, to the largest size that fits inside the area; if the mask is not repeated, the rest of the area is hidden.

Give a comma-separated list for multiple layers.

Usage notes

  • contain plus no-repeat for icons. The whole icon fits, and the remaining area is hidden. Add mask-position: center to center it.
  • Vector images scale cleanly. SVG masks stay sharp at any size; bitmap masks get blurry when enlarged.
  • SVGs need a viewBox or a size. An SVG with neither has no intrinsic ratio, and contain and cover then behave like auto.
  • Order of values. In the mask shorthand, size must follow the position after a slash: center / 50px.
  • Percentages refer to the area, not the element's content, and the area depends on mask-origin (default border-box).
  • Animate with care. Animating mask-size re-rasterizes the mask each frame and can be costly on large areas.

Browser support

Unprefixed mask-size works in current versions of the major browsers; older ones needed -webkit-mask-size.