CSS Reference Property

mask-size

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 the property. Unless the value of the mask-origin property is set by the author, it has value of border-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 to auto, 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.

View this demo on the Codrops Playground

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
  • 123
  • No
  • 123
  • 124

* denotes prefix required.

  • Supported:
  • Yes
  • No
  • Partially
  • Polyfill

Stats from caniuse.com

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.

Further Reading

Written by . Last updated December 11, 2016 at 10:38 pm by Manoela Ilic.

Do you have a suggestion, question or want to contribute? Submit an issue.