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.
.photo { mask-image: linear-gradient(to right, white, black); mask-mode: luminance; }
Try it
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
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
maskshorthand accepts the keywordsalpha,luminanceandmatch-sourceinside 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.
Related
maskโ the shorthandmask-imageโ the mask sourcemask-compositeโ combining layersmask-borderโ masks along a border- Lesson: Clip Paths and Masks