What Is CSS mask-type Luminance in SVG Masking

The CSS mask-type: luminance property determines whether an SVG <mask> element uses the brightness of its graphic content to calculate opacity rather than its transparency. When set to luminance, the mask converts color values into light intensity: pure white areas render the masked element fully opaque, pure black areas make it completely transparent, and intermediate grayscale tones generate varying levels of semi-transparency. This property bridges the gap between traditional SVG masking behaviors and modern CSS alpha masking.

The Purpose of mask-type: luminance

In CSS, masking can interpret mask sources in two distinct ways:

  • Alpha Masking (mask-type: alpha): Visibility is determined solely by the alpha channel (transparency) of the mask layer. The color or brightness of the mask graphic is completely ignored.
  • Luminance Masking (mask-type: luminance): Visibility is calculated based on the perceived brightness of the mask's colors. The alpha channel is still factored in, but the RGB values directly control opacity.

The mask-type property applies specifically to the SVG <mask /> element. While standard CSS masking via the mask-image property defaults to interpreting external raster images using alpha channels, native SVG masks historically used luminance as their default behavior. Applying mask-type: luminance explicitly declares that the SVG mask should read RGB brightness values to generate the clipping threshold.

How Luminance Is Calculated

The browser determines luminance using the standard relative luminance formula defined by the sRGB color space:

\[Luminance = 0.2126 \times R + 0.7152 \times G + 0.0722 \times B\]

Because the human eye is more sensitive to green than red or blue, green elements produce greater opacity than blue elements of equivalent color saturation. Once the luminance value is computed, it is multiplied by the mask content's existing alpha channel to generate the final mask transparency.

Basic Syntax and Implementation

The property can be declared directly in CSS targeted at an SVG <mask> element:

mask#my-luminance-mask {
  mask-type: luminance;
}

Or used in conjunction with SVG markup:

<svg width="0" height="0">
  <mask id="my-luminance-mask" style="mask-type: luminance;">
    <!-- White reveals the target -->
    <rect x="0" y="0" width="100" height="100" fill="white" />
    <!-- A linear gradient creates a fade effect -->
    <rect x="100" y="0" width="100" height="100" fill="url(#gray-fade)" />
    <!-- Black conceals the target -->
    <rect x="200" y="0" width="100" height="100" fill="black" />
  </mask>
</svg>

<div class="masked-element"></div>
.masked-element {
  width: 300px;
  height: 100px;
  background-color: royalblue;
  mask: url(#my-luminance-mask);
}

When to Use mask-type: luminance

Using luminance masking is beneficial in several common scenarios:

  1. Grayscale Mask Assets: When working with black-and-white graphics, depth maps, or standard contrast maps that do not contain an embedded transparent alpha channel.
  2. Standardizing Cross-Browser SVG Masks: While SVG specifications historically defaulted to luminance, declaring mask-type: luminance in CSS ensures consistent behavior when referencing SVG masks through standard CSS mask or mask-image rules.
  3. Complex Gradient Fades: It allows designers to create opacity gradients using simple color fills (such as fading from #ffffff to #000000) instead of configuring multi-stop transparent color stops.