mask-size

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:

Syntax

mask-size: <bg-size> = [ <length-percentage> = <length> | <percentage> | auto ]{1,2} | cover | contain

• Initial value: auto
• Applies to: All elements. In SVG, it applies to container elements excluding the <defs> element, all graphics elements and the <use> element
• Inherited: no
• Animation type: repeatable list

That’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).

• When two values are used, the first value specifies the width of the mask image, and the second value specifies its height.
• When one value that is not contain or cover is used, it defines the width of the mask image and the height is assumed to be auto.

Values

/* 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;

Value definitions

• <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.

Using multiple values

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;
}

The auto value

If 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:

• if the image has an intrinsic proportion, the auto value gets computed using the the specified dimension and the intrinsic proportion.
• if the image has no intrinsic proportion, the auto value becomes the image’s corresponding intrinsic dimension if it exists and, if it doesn’t, auto will be the corresponding dimension of the mask positioning area.

Understanding cover and contain

The 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.

And just what the heck is an intrinsic dimension and intrinsic proportion?

Intrinsic dimensions are width and height of an element and intrinsic proportion is ratio of them.

• A bitmap image like a PNG format, always has intrinsic dimensions and an intrinsic proportion.
• A vector image like a SVG format, may have both intrinsic dimensions. Therefore, it also has an intrinsic proportion. It also may have one or no intrinsic dimensions and, in either case, it might or might not have an intrinsic proportion.
• Gradients are like images with no intrinsic dimensions or intrinsic proportion.

Demo

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.

Browser support

IE	Edge	Firefox	Chrome	Safari	Opera
No	18+	53+	All	4+	70

Android Chrome	Android Firefox	Android Browser	iOS Safari	Opera Mini
85+	79+	4.4+	All	All

More information

Related properties