docs.rodeo

MDN Web Docs mirror

mask-size

{{CSSRef}} 

The mask-size CSS property specifies the sizes of specified mask images. Mask image sizes can be fully or partially constrained to preserve their {{glossary("aspect ratio", "intrinsic 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

The mask-size property accepts a comma-separated list of <bg-size> values. A <bg-size> value is either cover, 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 to auto). Values include:

Description

The mask-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 the {{cssxref("mask-image")}}  property value (a value creates a mask layer, even if it is none).

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

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

The width and height values are a {{cssxref("&lt;length&gt;")}} , a {{cssxref("&lt;percentage&gt;")}} , or the auto keyword, which is the default. Setting one or both values to auto maintains the mask image’s original aspect ratio.

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

Like with all longhand components of shorthand property, if the {{cssxref("mask")}}  shorthand property is set and the value of the mask-size property is not defined within any mask layer, the mask-size value is reset to its initial value of auto for those mask layers.

Formal definition

{{cssinfo}} 

Formal syntax

{{csssyntax}} 

Examples

Setting mask size as a percentage

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

HTML

We include two {{htmlelement("div")}}  elements:

<div class="width"></div>
<div class="height"></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(https://mdn.github.io/shared-assets/images/examples/mdn.svg);
}

The width of one <div> element’s mask is set to 50%, with the height defaulting to auto. The mask’s height for the second <div> element is set to 50% with the width set to auto:

.width {
  mask-size: 50%;
}

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

In the width case, the mask is rendered 100px wide (50% of the 200px-wide element). The height defaults to auto, maintaining the mask’s aspect ratio. In the height case, the mask is rendered 200px tall (50% of the 400px-high container). The width is explicitly set to auto, maintaining the mask’s aspect ratio.

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

Results

{{EmbedLiveSample("Setting mask size as a percentage", "", "430px")}} 

Cover and contain

This example demonstrates the keyword values for mask-size.

HTML

Three {{htmlelement("section")}}  elements are defined, each with a different class name, and each containing a <div>.

<section class="auto">
  <div></div>
</section>
<section class="cover">
  <div></div>
</section>
<section class="contain">
  <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(https://mdn.github.io/shared-assets/images/examples/mask-star.svg);
}

The mask-size of two of the <div> elements is set to one of the property’s keyword values. The third <div> has a mask-size of auto 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 using generated 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

{{EmbedLiveSample("Cover and contain", "", "430px")}} 

With auto, the star is displayed at its intrinsic 100px by 100px size. With cover, the star grows to be 400px tall, covering the entire origin box. With contain, the star grows until one dimension equals the same dimension of the origin 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 class="auto">
  <div></div>
</section>
<section class="cover">
  <div></div>
</section>
<section class="contain">
  <div></div>
</section>

div {
  background: blue linear-gradient(red, blue);
  mask-image: url(https://mdn.github.io/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;
}

{{EmbedLiveSample("When the mask is larger than the container", "", "120px")}} 

The contain value contains the mask within the origin box. The cover value covers it. In both cases, the mask shrinks while maintaining the original aspect ratio. With auto, the mask is clipped because the intrinsic dimensions are larger than the box dimensions.

Specifications

{{Specifications}} 

Browser compatibility

{{Compat}} 

See also

In this article

View on MDN