mask CSS property

Constituent properties

This property is a shorthand for the following CSS properties:

• mask-clip
• mask-composite
• mask-image
• mask-mode
• mask-origin
• mask-position
• mask-repeat
• mask-size

Syntax

/* Keyword values */
mask: none;

/* Image values */
mask: url("mask.png"); /* Raster image used as mask */
mask: url("masks.svg#star"); /* SVG used as mask */

/* Combined values */
mask: url("masks.svg#star") luminance; /* Luminance mask */
mask: url("masks.svg#star") 40px 20px; /* Mask positioned 40px from the top and 20px from the left */
mask: url("masks.svg#star") 0 0/50px 50px; /* Mask with a width and height of 50px */
mask: url("masks.svg#star") repeat-x; /* Horizontally-repeated mask */
mask: url("masks.svg#star") stroke-box; /* Mask extends to the inside edge of the stroke box */
mask: url("masks.svg#star") exclude; /* Mask combined with background using non-overlapping parts */

/* Multiple masks */
mask:
  url("masks.svg#star") left / 16px repeat-y,
  /* 16px-wide mask on the left side */ url("masks.svg#circle") right / 16px
    repeat-y; /* 16px-wide mask against right side */

/* Global values */
mask: inherit;
mask: initial;
mask: revert;
mask: revert-layer;
mask: unset;

Values

<mask-layer>

One or more comma-separated mask layers, consisting of the following components:

<mask-reference>

Sets the mask image source. See mask-image.

<masking-mode>

Sets the masking mode of the mask image. See mask-mode.

<position>

Sets the position of the mask image. See mask-position.

<bg-size>

Sets the size of the mask image. See mask-size.

<repeat-style>

Sets the repetition of the mask image. See mask-repeat.

<geometry-box>

If only one <geometry-box> value is given, it sets both the mask-origin and mask-clip property values. If two <geometry-box> values are present, the first defines the mask-origin and the second defines the mask-clip.

<geometry-box> | no-clip

Sets the area affected by the mask image. See mask-clip.

<compositing-operator>

Sets the compositing operation used on the current mask layer. See mask-composite.

Description

The mask shorthand property hides part or all of the element it is applied to. The parts of the element that are hidden, visible, or partially shown depend on either the opacity (alpha channel of the mask) or the brightness (luminance) of the mask. In alpha masking, opaque areas of the mask reveal the element, and transparent areas hide it. In luminance masking, light opaque areas of the mask reveal the element, and dark or transparent areas hide it.

While not all constituent mask properties need to be declared, any values that are omitted default to their initial values, which are:

mask-image: none;
mask-mode: match-source;
mask-position: 0% 0%;
mask-size: auto;
mask-repeat: repeat;
mask-origin: border-box;
mask-clip: border-box;
mask-composite: add;

Within each <mask-layer>, the mask-size component must go after the mask-position value, with a forward slash (/) separating the two.

If there are two <geometry-box> values present, the first is the mask-origin value, while the second is the mask-clip value. If one <geometry-box> value and the no-clip keyword are present, the <geometry-box> is the value of the mask-origin property, as the no-clip is only valid for the mask-clip property. In this case, the order of the two values doesn't matter. If only one <geometry-box> value is present (with no no-clip keyterm specified), this value is used for both the mask-origin and mask-clip properties.

As the mask shorthand resets all the mask-border-* properties to their initial value, you should declare these properties — or the mask-border shorthand — after any mask declarations. When setting mask in your declaration block, you also implicitly set the following:

mask-border-source: none;
mask-border-mode: alpha;
mask-border-outset: 0;
mask-border-repeat: stretch;
mask-border-slice: 0;
mask-border-width: auto;

For this reason, the specification recommends using the mask shorthand rather than the individual component properties to override any masks set earlier in the cascade. This ensures that mask-border has also been reset.

Formal definition

Formal syntax

mask = 
  <mask-layer>#  

<mask-layer> = 
  <mask-reference>              ||
  <position> [ / <bg-size> ]?   ||
  <repeat-style>                ||
  <geometry-box>                ||
  [ <geometry-box> | no-clip ]  ||
  <compositing-operator>        ||
  <masking-mode>                

<mask-reference> = 
  none           |
  <image>        |
  <mask-source>  

<position> = 
  <position-one>   |
  <position-two>   |
  <position-four>  

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

<repeat-style> = 
  repeat-x           |
  repeat-y           |
  repeat-block       |
  repeat-inline      |
  <repetition>{1,2}  

<geometry-box> = 
  <shape-box>  |
  fill-box     |
  stroke-box   |
  view-box     

<compositing-operator> = 
  add        |
  subtract   |
  intersect  |
  exclude    

<masking-mode> = 
  alpha         |
  luminance     |
  match-source  

<image> = 
  <url>           |
  <image()>       |
  <image-set()>   |
  <cross-fade()>  |
  <element()>     |
  <gradient>      

<mask-source> = 
  <url>  

<position-one> = 
  left                 |
  center               |
  right                |
  top                  |
  bottom               |
  x-start              |
  x-end                |
  y-start              |
  y-end                |
  block-start          |
  block-end            |
  inline-start         |
  inline-end           |
  <length-percentage>  

<position-two> = 
  [ left | center | right | x-start | x-end ] && [ top | center | bottom | y-start | y-end ]  |
  [ left | center | right | x-start | x-end | <length-percentage> ] [ top | center | bottom | y-start | y-end | <length-percentage> ]  |
  [ block-start | center | block-end ] && [ inline-start | center | inline-end ]  |
  [ start | center | end ]{2}                         

<position-four> = 
  [ [ left | right | x-start | x-end ] <length-percentage> ] && [ [ top | bottom | y-start | y-end ] <length-percentage> ]  |
  [ [ block-start | block-end ] <length-percentage> ] && [ [ inline-start | inline-end ] <length-percentage> ]  |
  [ [ start | end ] <length-percentage> ]{2}          

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

<repetition> = 
  repeat     |
  space      |
  round      |
  no-repeat  

<shape-box> = 
  <visual-box>     |
  margin-box       |
  half-border-box  

<image()> = 
  image( <image-tags>? [ <image-src>? , <color>? ]! )  

<image-set()> = 
  image-set( <image-set-option># )  

<cross-fade()> = 
  cross-fade( <cf-image># )  

<element()> = 
  element( <id-selector> )  

<visual-box> = 
  content-box  |
  padding-box  |
  border-box   

<image-tags> = 
  ltr  |
  rtl  

<image-src> = 
  <url>     |
  <string>  

<image-set-option> = 
  [ <image> | <string> ] [ <resolution> || type( <string> ) ]?  

<cf-image> = 
  [ <image> | <color> ]  &&
  <percentage [0,100]>?  

<id-selector> = 
  <hash-token>  

Examples

Masking an image

In this example, an image is masked using a CSS-generated repeating conic gradient as a mask source. We'll also show the gradient as a background image for comparison.

HTML

We include an <img> and an empty <div> element.

<img
  src="https://mdn.github.io/shared-assets/images/examples/progress-pride-flag.jpg"
  alt="Pride flag" />
<div></div>

CSS

We set the same border, padding, and sizing on both the <img> and <div>.

img,
div {
  border: 20px dashed rebeccapurple;
  box-sizing: content-box;
  padding: 20px;
  height: 220px;
  width: 220px;
}

We then apply a mask to the <img>. The mask-image is generated using a repeating-conic-gradient() function. We define it to be a 100px by 100px gradient, which repeats starting at the top and left corner of the image's content-box. We include two <geometry-box> values; the first sets the mask-origin and the second defines the mask-clip property value. The gradient goes from transparent to solid lightgreen. We used lightgreen to demonstrate that it isn't the color of the mask that is important, but rather its transparency.

img {
  mask: repeating-radial-gradient(
      circle,
      transparent 0 5px,
      lightgreen 15px 20px
    )
    content-box border-box 0% 0% / 100px 100px repeat;
}

Finally, we use the same value for the <div>'s background shorthand property as we used for the mask.

div {
  background: repeating-radial-gradient(
      circle,
      transparent 0 5px,
      lightgreen 15px 20px
    )
    content-box border-box 0% 0% / 100px 100px repeat;
}

Results

Specifications

Browser compatibility

See also

• clip-path
• filter
• Introduction to CSS masking
• CSS mask properties
• Declaring multiple masks
• CSS masking module
• SVG mask attribute
• Applying SVG effects to HTML content