The mask-mode property's default value — match-source — sets the mode to either alpha or luminance, depending on the value. The match-source value resolves to alpha for all mask sources other than SVG <mask> elements. If the mask source is a <mask> element, match-source resolves to the <mask>'s mask-type property value, if set. Otherwise, it resolves to the value of the SVG mask-type attribute set on the <mask> element. If that is not explicitly set either, match-source will resolve to luminance.
If mask-mode resolves to luminance, or we explicitly set it to luminance, the colors of the mask will affect the mask opacity. In the previous demo, the mask-mode was not set, so the value defaulted to match-source. As the colorful heart image is a transparent PNG, match-source resolves to alpha. By explicitly setting this property, we can control the mode. In this demo, we change the mask-mode to luminance.
.applied-mask {
mask-mode: luminance;
}
When applying mask-mode: luminance to the same mask as in the previous example, the areas of the element where the mask is lightest are more opaque, while darker areas are less opaque.
The opacity of a luminance mask is determined by the R, G, B, and A values of an RGB color using the formula:
((0.2125 * R) + (0.7154 * G) + (0.0721 * B)) * A
For example, the newest <named-color> is rebeccapurple, which is #663399. While one might assume the lightness might be equivalent to the L of the hsl() color function, it's not that simple. The value #663399 is equivalent to rgb(40% 20% 60% / 1) and hsl(270 50% 40% / 1), but the brightness value is 27.134%, not 40%.
((0.2125 * 0.4) + (0.7154 * 0.2) + (0.0721 * 0.6)) * 1 = 0.27134
White has a brightness value of 100%.
((0.2125 * 1) + (0.7154 * 1) + (0.0721 * 1)) * 1 = 1
Black's brightness is 0%.
((0.2125 * 0) + (0.7154 * 0) + (0.0721 * 0)) * 1 = 0
We'll demonstrate this by adding white (rgb(100% 100% 100%)) with a lightness of 100% at 27.234% opacity to a rebeccapurple, white, and black linear gradient, which we'll then use to mask our image. This white resolves to the same opacity value:
((0.2125 * 1) + (0.7154 * 1) + (0.0721 * 1)) * 0.27134 = 0.27134
.applied-mask {
mask-image: repeating-linear-gradient(
to bottom left,
rebeccapurple 0 20px,
rgb(100% 100% 100% / 0.27134) 20px 40px,
black 40px 45px,
white 45px 50px
);
mask-mode: luminance;
}
.mask-source {
background: repeating-linear-gradient(
to bottom left,
rebeccapurple 0 20px,
rgb(100% 100% 100% / 0.27134) 20px 40px,
black 40px 45px,
white 45px 50px
);
}
The areas with a white mask are fully opaque. The areas with a black mask are fully transparent. The areas with a rebeccapurple mask and the areas with a 27.1234% opaque white mask are both 27.1234% opaque.
If you toggle the mask-mode to alpha, the color of the gradient no longer matters. The entire element will be opaque except the areas covered by the semi-opaque white.
The mask-mode property enables using raster images without alpha transparency, such as JPEGs, as mask images. A JPEG is made up of opaque pixels. Using a JPEG as a mask with its default alpha mask mode would hide the entire element. The luminance value of mask-mode, on the other hand, clips the element where the mask is black (has no lightness), is fully opaque where the mask is opaque white (100% lightness), with other areas being semi-transparent based on the lightness of the mask area masking it.
In this example, we have a white moon against a black night sky.
.applied-mask {
mask-image: url(https://mdn.github.io/shared-assets/images/examples/moon.jpg);
mask-mode: luminance;
mask-size: 220px;
}
.mask-source {
background: url(https://mdn.github.io/shared-assets/images/examples/moon.jpg);
background-size: 220px;
}
The element is clipped and not visible where the sky is black. The image is most visible where the moon is at it's lightest.
In this case, if you toggle the mask-mode to alpha, the entire element will be visible as the entire mask is opaque.
