In CSS, the mask-size property specifies the size of a mask layer image. In many ways, it works very much like the background-size property.
.element {
mask-image: url(star.svg);
mask-size: 200px 100px;
}Masking allows you to display selected parts of an element while hiding the rest. The size of the mask is defined by the mask-size property.
In the following demo you can play around with the size of the mask layer image:
mask-size: <bg-size> = [ <length-percentage> = <length> | <percentage> | auto ]{1,2} | cover | contain<defs> element, all graphics elements and the <use> elementThat’s basically saying that the syntax accepts a background size (<bg-size>) value that can either be one or two lengths and/or percentages (<length-percentage>), set to auto, or one of two keywords (cover and contain).
auto./* Lengths */
mask-size: 200px; /* width is 200px and height is auto */
mask-size: 50% 100%; /* width is 50% and height is 100% */
/* Keywords */
mask-size: contain;
mask-size: cover;
/* Global values */
mask-size: auto;
mask-size: intial;
mask-size: inherit;
mask-size: unset;<length>: Any valid and non-negative CSS length, such as px, em, rem and %, among others.<percentage>: Specifies the size of mask layer image as a percentage value relative to the mask positioning area, which is set by the value of mask-origin. By default, this value is border-box, meaning that it contains borders, padding and content of the box.auto: The intrinsic height and width of the mask image is used and, for images like gradients which don’t have intrinsic dimensions, it is rendered at the size of the mask positioning area.contain: Scales the mask image while preserving its intrinsic proportion in a way that both its width and its height can fit inside the mask positioning area. For the images like gradients that don’t have intrinsic dimensions, it is rendered at the size of the mask positioning area.cover: Scales the mask image while preserving its intrinsic proportion in a way that both its width and its height can entirely cover the mask positioning area. For the images like gradients that don’t have intrinsic dimensions, it is rendered at the size of the mask positioning area.initial: Applies the property’s default setting, which is auto.inherit: Adopts the mask-size value of the parent.unset: Removes the current mask-size from the element.This property can take a comma-separated list of values for mask sizes and each value is applied to a corresponding mask layer image specified in the mask-image property.
In the following example, the first value specifies the size of the first image, the second value specifies the size of the second image, and so on.
.element {
mask-image: url(image1.png), url(image2.png), url(image3.png);
mask-size: 100px 100%, auto, contain;
}auto valueIf the value of the mask-size property is specified as auto, like this:
.element {
mask-size: auto auto;
/* or */
mask-size: auto;
}…then the mask image scales in the corresponding directions in order to maintain its aspect ratio. That said, we can get various results depending on the image’s intrinsic dimensions and proportion.
| Proportion/Dimension | No intrinsic dimensions | One intrinsic dimension | Both intrinsic dimensions |
|---|---|---|---|
| Has Proportion | Rendered as if contain had been specified instead | Rendered at the size determined by that one dimension and the proportion | Rendered at that size |
| No Proportion | Rendered at the size of the mask positioning area | Rendered using the intrinsic dimension and the corresponding dimension of the mask positioning area | N/A |
If the value of mask-size is specified with auto and another non-auto value like the following:
.element {
mask-size: auto 200px;
}…then:
cover and containThe following video explains how the contain and cover keywords work. Note that the initial position of a mask layer is at the center of the positioning area:
If the image has no intrinsic aspect ratio, then specifying either cover or contain renders the mask image at the size of the mask positioning area.
Intrinsic dimensions are width and height of an element and intrinsic proportion is ratio of them.
The following demo uses a length for the mask-size. Try change the value to other types of values in the code and check the result.
.element { mask-clip: padding-box; }
.element { mask-image: url(star.svg); }
.element { mask-mode: alpha; }
.element { mask-origin: content-box; }
.element { mask-position: 20px center; }
.element { mask-repeat: repeat-y; }
.element { mask-type: alpha; }