Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท Filters, Masks and Shapes

The mask-mode property

Reference for the CSS mask-mode property: choose whether a mask uses its alpha channel or its brightness (luminance) to decide what stays visible.

The mask-mode property chooses which part of the mask image controls visibility. With alpha, opaque pixels show the element and transparent pixels hide it. With luminance, the brightness of each pixel decides: white shows the element, black hides it, and grays are in between.

The default, match-source, picks alpha for ordinary images and gradients, and luminance for masks that reference an SVG <mask> element. This keeps old SVG masks working while giving modern CSS images the more intuitive alpha behavior.

CSS
.photo {
  mask-image: linear-gradient(to right, white, black);
  mask-mode: luminance;
}

Try it

Alpha versus luminance with the same gradient

The mask goes from opaque white to opaque black. With alpha both ends are fully opaque, so the whole box shows. With luminance, white shows and black hides, so the box fades out to the right.

Syntax

CSS
mask-mode: <masking-mode>#

/* <masking-mode> = alpha | luminance | match-source */
  • Initial value: match-source
  • Applies to: all elements; in SVG, container elements (except <defs>) and graphics elements
  • Inherited: no
  • Animatable: no
  • Computed value: as specified

Values

Value Description
match-source Uses alpha for images, gradients and other CSS images; uses luminance for a url() reference to an SVG <mask> element.
alpha Visibility comes from the alpha channel of the mask pixels. Color is ignored.
luminance Visibility comes from the brightness of the mask pixels, multiplied by their alpha. Light colors show more, dark colors less.

Give a comma-separated list to set a mode per mask layer.

Usage notes

  • Luminance masks are handy with black-and-white art. Existing grayscale masks (for example from a design tool) work without being converted to transparency.
  • Transparent pixels hide in both modes. In luminance, a pixel's contribution is its brightness times its alpha, so transparent pixels never show.
  • Match your color space. Luminance is calculated from the pixel color; a mid-gray gives about half visibility, but it is not exactly 50% in every color space, so check by eye.
  • The default is usually right. Set the property only when you load a gray-scale mask image or need to override the SVG <mask> default.
  • Shorthand. The mask shorthand accepts the keywords alpha, luminance and match-source inside a layer.

Browser support

mask-mode is newer than the basic mask properties, so check a compatibility table before relying on luminance in production; where it is unsupported, the mask behaves as alpha.