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.
.icon { mask-image: url(icon.svg); mask-repeat: no-repeat; mask-position: center; mask-size: contain; }
Try it
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
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
containplusno-repeatfor icons. The whole icon fits, and the remaining area is hidden. Addmask-position: centerto center it.- Vector images scale cleanly. SVG masks stay sharp at any size; bitmap masks get blurry when enlarged.
- SVGs need a
viewBoxor a size. An SVG with neither has no intrinsic ratio, andcontainandcoverthen behave likeauto. - Order of values. In the
maskshorthand, 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(defaultborder-box). - Animate with care. Animating
mask-sizere-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.
Related
maskโ the shorthandmask-positionโ where the mask sitsmask-repeatโ tilingbackground-sizeโ the same values for backgrounds- Lesson: Clip Paths and Masks