Themask-sizeCSS property specifies the sizes of specified mask images. Mask image sizes can be fully or partially constrained to preserve theirintrinsic aspect ratios.

Syntax

/* Keyword syntax */mask-size: cover;mask-size: contain;mask-size: auto;/* One-value syntax *//* Mask width. Sets height to 'auto'. */mask-size: 50%;mask-size: 3em;mask-size: 12px;/* Two-value syntax *//* First value: mask width. Second value: mask height */mask-size: 3em 25%;mask-size: auto 6px;mask-size: auto 50%;/* Multiple values */mask-size: auto, contain;mask-size:  50%,  50% 25%,  auto 25%;mask-size: 6px, auto, contain;/* Global values */mask-size: inherit;mask-size: initial;mask-size: revert;mask-size: revert-layer;mask-size: unset;

Values

Themask-size property accepts a comma-separated list of<bg-size> values. A<bg-size> value is eithercover,contain, a pair of values specifying the width and height (in that order), or a single value specifying the width (in which case, the height is set toauto). Values include:

contain

Scales the mask image up or down, while preserving its aspect-ratio, making the mask as large as possible within its container without cropping or stretching it.If the mask image is smaller than the container, the mask will tile, or repeat, unless themask-repeat property is set tono-repeat.

cover

Scales the mask image to the smallest possible size to fill the container while preserving its aspect ratio. If the aspect ratio of the mask image differs from the element, it will be cropped vertically or horizontally.

auto

Maintains the original aspect ratio of the mask source. When set for both the width and height, the origin size of the mask resource is used. Otherwise,auto scales the mask image in the corresponding direction such that its original aspect ratio is maintained.

<length>

Renders the mask image at the specified length in the corresponding dimension (width if set as the first or only value, height if set as the second value). Negative values are not allowed.

<percentage>

Renders the mask image in the corresponding dimension to the specified percentage of the box origin area as defined by themask-origin property, which defaults topadding-box. Negative values are not allowed.

Description

Themask-size property is used to size mask layers.

An element can have multiple mask layers applied. The number of mask layers is determined by the number of comma-separated values in themask-image property value (a value creates a mask layer, even if it isnone).

Eachmask-size value in the comma-separated list of values is matched up with an associated mask layer as defined by the list ofmask-image values, in order. If the number of values in the two properties differs:

• Ifmask-size has more values thanmask-image, the excess values ofmask-size are not used.
• Ifmask-size has fewer values thanmask-image, themask-size values are repeated.

Eachmask-size value is a<bg-size> value. There are three ways to declare each<bg-size>: one keyword, two lengths, percentages or the keywordauto, or one length, percentage, orauto:

• The available keywords arecover andcontain.
• When two values are specified, the first defines the mask width and the second defines its height.
• When one value is specified, it defines only the mask width, with the height set toauto.

The width and height values are a<length>, a<percentage>, or theauto keyword, which is the default. Setting one or both values toauto maintains the mask image's original aspect ratio.

The rendered size of the mask image is computed as follows:

• If both components ofmask-size are specified and are notauto, the mask image renders at the specified size.
• If themask-size iscontain orcover, the image is rendered by preserving its aspect ratio at the largest size contained within or covering the mask positioning area. If the image has no intrinsic proportion, such as with gradients, then it is rendered at the size of the mask positioning area.
• If themask-size isauto (which resolves toauto auto), it is rendered at the size at which the mask would be displayed if no CSS were applied to change the rendering; this is itsintrinsic size. If it has no intrinsic dimensions and no intrinsic proportion, as is the case withCSS gradients, it is rendered at the size of the mask positioning area, defined by themask-origin (which defaults toborder-box).If the mask source has no dimensions but has a proportion (aspect-ratio), a value ofauto will render it as ifcontain had been specified instead. If the image has one intrinsic dimension and a proportion, it is 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.
• Ifmask-size has oneauto component and one non-auto component, which applies to all single-value values, the aspect ratio is maintained if the mask source has an intrinsic proportion. If there are no intrinsic proportions, theauto value is assumed to be the dimension of the mask positioning area.

Like with all longhand components of shorthand property, if themask shorthand property is set and the value of themask-size property is not defined within any mask layer, themask-size value is reset to its initial value ofauto for those mask layers.

Formal definition

Formal syntax

mask-size =
<bg-size>#

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

<length-percentage> =
<length>|
<percentage>

Examples

Setting mask size as a percentage

This example demonstrates basic usage, while also demonstrating percentage values formask-size.

HTML

We include two<div> elements:

<div></div><div></div>

CSS

The<div> elements are defined to be twice as tall as they are wide, with a gradient background and mask:

div {  width: 200px;  height: 400px;  background: blue linear-gradient(red, blue);  mask-image: url("/shared-assets/images/examples/mdn.svg");}

The width of one<div> element's mask is set to50%, with the height defaulting toauto. The mask's height for the second<div> element is set to50% with the width set toauto:

.width {  mask-size: 50%;}.height {  mask-size: auto 50%;}

In thewidth case, the mask is rendered100px wide (50% of the200px-wide element). The height defaults toauto, maintaining the mask's aspect ratio.In theheight case, the mask is rendered200px tall (50% of the400px-high container). The width is explicitly set toauto, maintaining the mask's aspect ratio.

body {  display: flex;  gap: 20px;}

Results

Cover and contain

This example demonstrates the keyword values formask-size.

HTML

Three<section> elements are defined, each with a different class name, and each containing a<div>.

<section>  <div></div></section><section>  <div></div></section><section>  <div></div></section>

CSS

The<div> elements are defined to be twice as tall as they are wide, with a gradient background and mask:

div {  width: 200px;  height: 400px;  background: blue linear-gradient(red, blue);  mask-image: url("/shared-assets/images/examples/mask-star.svg");}

Themask-size of two of the<div> elements is set to one of the property's keyword values. The third<div> has amask-size ofauto set demonstrating the original intrinsic dimensions of the mask:

.auto div {  mask-size: auto;}.cover div {  mask-size: cover;}.contain div {  mask-size: contain;}

The property values is displayed usinggenerated content.

section::before {  content: "mask-size: " attr(class) ";";  display: block;  text-align: center;  border-bottom: 1px solid;}

body {  display: flex;  flex-flow: row wrap;  gap: 10px;}section {  border: 1px solid;}

Results

Withauto, the star is displayed at its intrinsic100px by100px size. Withcover, the star grows to be400px tall, covering the entire origin box. Withcontain, the star grows until one dimension equals the same dimension of theorigin box, meaning that the star is as large as it can be (200px wide) but still contained by it.

When the mask is larger than the container

Using the same HTML and CSS as above, with just a different origin box size, this example explores what happens when the origin box is smaller than the intrinsic dimensions of the mask.

<section>  <div></div></section><section>  <div></div></section><section>  <div></div></section>

div {  background: blue linear-gradient(red, blue);  mask-image: url("/shared-assets/images/examples/mask-star.svg");}.auto div {  mask-size: auto;}.cover div {  mask-size: cover;}.contain div {  mask-size: contain;}section::before {  content: attr(class);  display: block;  text-align: center;  border-bottom: 1px solid;}body {  display: flex;  flex-flow: row wrap;  gap: 10px;}section {  border: 1px solid;}

The only difference is the size of the containing box (and the generated content):

div {  width: 70px;  height: 70px;}

Thecontain value contains the mask within the origin box. Thecover value covers it. In both cases, the mask shrinks while maintaining the original aspect ratio. Withauto, the mask is clipped because the intrinsic dimensions are larger than the box dimensions.

Specifications

Browser compatibility

See also

• background-size
• mask shorthand
• mask-image
• mask-origin
• mask-position
• mask-repeat
• mask-image
• mask-border
• background-size
• mask-border-width
• Introduction to CSS masking
• CSSmask properties
• Declaring multiple masks
• CSS masking module