CSS mask-size Property

The mask-size property controls how an element’s mask image(s) are scaled when they are painted over the element. It determines the rendered dimensions of the mask content relative to the mask positioning area, which in turn affects which parts of the underlying element remain visible or hidden. Because a mask is effectively a coverage map (alpha or luminance values that modulate an element’s opacity), changing the mask’s scale can dramatically alter edges, gradients, and the apparent softness or hardness of transitions between visible and masked-away regions.

Scaling behavior must be considered alongside the source of the mask itself — for example, whether the mask comes from an image, an SVG, or a CSS gradient — since different sources have different intrinsic sizes and aspect ratios. The chosen scale interacts with the mask resource specified via mask-image; when a mask image has an intrinsic size, mask-size decides whether that intrinsic size is preserved, stretched, or reduced. It also works together with mask-repeat, because scaled-down masks that repeat will tile differently than full-size or scaled-up ones, and scaled-up repeating masks can introduce unexpected seams or interpolation artifacts.

Conceptually, mask-size behaves much like the sizing controls used for background artwork; authors familiar with background-size will find the mental model similar: you are controlling how large the mask paint is relative to the element. Positioning and anchoring of that scaled mask are then handled separately (see mask-position), so it’s common to think of sizing and positioning as two distinct steps — first establish how large the mask should be, then where it should sit inside the element. This separation lets you create responsive masking effects: for example, scaling a mask proportionally to the element’s size or fixing the mask to a specific pixel size regardless of the element’s dimensions.

In practical terms, using mask-size lets you create a wide range of visual effects: crisp cutouts or soft feathered edges by shrinking or enlarging a gradient mask, repeating patterned masks at a controlled scale, or fitting vector masks to a particular area without distortion. When layering multiple masks, each layer’s size can be controlled independently, enabling complex composite masking. Because scaling can introduce interpolation and anti-aliasing, designers often combine careful sizing with appropriate mask sources and repetition/position choices to preserve clarity and achieve the intended visual result.