The mask-size
property is used to specify the size of a mask layer image.
A mask layer image can be set to have specific dimensions using absolute length values or percentage values. It can also be sized so that it covers the entire mask painting area using two keywords—cover
and contain
—while preserving its intrinsic ratio of height to width, if the image used has a ratio.
For example, some <image>
s have intrinsic dimensions and proportions, such as JPEG images, for example, and other images such as <gradient>
s don’t have intrinsic dimensions and proportions and take up the size of the element’s mask image area unless specified otherwise (see values below). The final size of the mask layer image is rendered depending on whether an image has intrinsic dimensions and proportions.
The mask-size
property takes either a keyword value (cover
or contain
), or a pair of non-keyword values (<length>
| <percentage>
), or a non-keyword value and the value auto
. For example:
.examples { mask-size: cover; /* keyword value */ mask-size: contain; /* keyword value */ mask-size: 100% 50%; /* pair of non-keyword values */ mask-size: 300px 200px; /* pair of non-keyword values */ mask-size: 50% auto; /* non-keyword value + the value `auto` */ }
For pair values, the first value specifies the width of the mask image, and the second value specifies its height.
If only one non-keyword value is specified, the other one is assumed to be auto
.
Official Syntax
-
Syntax:
mask-size: <bg-size># /* where */ <bg-size> = [ <length> | <percentage> | auto ]{1,2} | cover | contain
- Initial: auto
- Applies To: All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
- Animatable: yes, except keyword values
Notes
The hash tag (#) indicates that the property takes any number of mask image sizes. The list of mask sizes is comma-separated.
When the mask-size
property takes a list of comma-separated values, each value is applied to a corresponding mask layer image specified in the mask-image
property (first value for the first image, second value for the second image, and so on).
Values
- <length>
-
A
<length>
value scales the mask layer image to the specified value in the corresponding direction. Negative lengths are not allowed. - <percentage>
-
A
<percentage>
value scales the mask layer image to the specified percentage value relative to the mask positioning area, which is determined by the value of theproperty
. Unless the value of themask-origin
property is set by the author, it has value ofborder-box
, which means that the mask image is positioned with respect to a coordinate system whose center is at the top left corner of the border box. Negative percentage values are not allowed. - contain
- Scale the mask image, while preserving its intrinsic aspect ratio (if any), to the largest size such that both its width and its height can fit inside the mask positioning area. If the mask image has no intrinsic proportion and no intrinsic dimension, then it is rendered at the size of the mask positioning area.
- cover
- Scale the mask image, while preserving its intrinsic aspect ratio (if any), to the smallest size such that both its width and its height can completely cover the mask positioning area. If the mask image has no intrinsic proportion and no intrinsic dimension, then it is rendered at the size of the mask positioning area.
- auto
-
The
auto
keyword that scales the mask layer image in the corresponding direction such that its intrinsic proportion is maintained.- If the image has both intrinsic dimensions (height and width), it’s going to be rendered at its size.
- If the mask image has no intrinsic proportion and no intrinsic dimension, then it is rendered at the size of the mask positioning area.
- If it has no dimensions but has a proportion, it’s rendered as if
contain
had been specified instead. - If the image has one intrinsic dimension and a proportion, it’s rendered at the size determined by that one dimension and the proportion.
- If the image has one intrinsic dimension but no proportion, it’s rendered using the intrinsic dimension and the corresponding dimension of the mask positioning area.
Notes
If the value of the mask-size
property is a pair where one value is auto
and the other value is <length>
or <percentage>
then:
-
If the image has intrinsic proportions: Use the length/percentage value specified to render the image in the corresponding dimension, and then use the image’s proportions to calculate the value of the other dimension. So, if, for example, the first value is a length and second value is
auto
, then the width of the image will be rendered to the specified length, and the height of the image will be calculated based on the image’s proportions. -
If the image does not have an intrinsic proportion: Use the length/percentage value to render the image in the corresponding dimension. For the other direction (which gets the
auto
value), the browser will use the image’s dimension if it has one. For example, a jpeg image has two intrinsic dimensions (height and width), so if a height is set to a length value, and the width is set toauto
, the browser will extract that width from the image and use it, because it has one. But if the image does not have an intrinsic width (e.g. a gradient), the browser will render it to have the same dimension as the mask positioning area.
The mask-size
property can also inherit the value of the mask size specified on its parent element by using the value inherit
. For example: mask-size: inherit;
.
Examples
The following are all valid syntaxes for the mask-size
property.
.examples { /* keyword value syntax */ mask-size: cover; mask-size: contain; /* two-value syntax: first value specifies the width of the image and the second value specifies its height */ mask-size: 50% auto; mask-size: 50px 30px; mask-size: 10em 12em; /* one-value syntax: the second value is always assumed to be `auto` */ mask-size: 32em; mask-size: auto; mask-size: 100%; }
The following are all examples of mask image sizes specified with the mask-size
property. The image in this example is assumed to be one with intrinsic dimensions and proportions (a PNG image, for example);
.examples { /* stretch the image to fill the mask area ignoring image ratio */ mask-size: 100% 100%; /* the mask image is shown at its intrinsic size */ mask-size: auto; /* default */ /* the mask is shown with a width of 3em and its height is scaled proportionally to keep the original aspect ratio */ mask-size: 3em; /* second value is assumed `auto` */ /* this one forces the mask image to be 15px by 15px */ mask-size: 15px 15px; }
The following example stretches the image so that exactly two copies fit horizontally (notice the values of the mask-repeat
property and the mask-origin
property). The aspect ratio is preserved.
.examples { mask-size: 50% auto; mask-repeat: repeat; mask-origin: border-box; }
The following example specifies the mask size of two mask images. The first value specifies the size of the first image, and the second value specifies the size of the second image.
.examples { mask-image: url(path/to/first/image.png), url(path/to/second/image.png); mask-size: 100% 100%, contain; }
Live Demo
Change the values of the mask-size
property in the following demo to see how it changes the rendering of the background image. Depending on the size of the mask, you can see more or less of the image beneath it.
Browser Support
CSS Masks
Method of displaying part of an element, using a selected image as a mask
W3C Candidate Recommendation
Supported from the following versions:
Desktop
- 120
- 53
- No
- 106
- 15
Mobile / Tablet
- 15
- 129
- No
- 129
- 130
Notes
This module, as you can see in the support table above, hasn’t been fully implemented in all browsers, so you’re probably not going to be able to use all features even in browsers that have implemented certain properties (for the time being).
In the meantime, you can check out this open source feature support table by Alan Greenblatt on GitHub. The purpose of this table is to provide some insight into what the current state of affairs is with various browser implementations of CSS Clipping and Masking features.