CSS mask-mode Property

The mask-mode property controls how the pixel data of mask sources is interpreted when producing the coverage map that determines which parts of an element are revealed or obscured. In practice this means it decides whether the mask content is treated primarily as transparency information (how opaque each pixel is) or as a tonal/brightness map (how light or dark pixels contribute to coverage). That interpretation is applied to the source images, gradients, or other painting primitives that make up the mask before those results are used to affect the element’s rendering.

Because interpretation happens per source, choosing the mode changes not only the look of a single mask layer but also how multiple mask layers interact. Each layer’s pixels are converted into a coverage image according to the chosen mode, and those coverage images are then combined according to the compositing rules set elsewhere (for example, in mask-composite). The separation between “how to read a mask” and “how to combine masks” is important: a given bitmap may behave like a soft fade in one interpretation and like a hard punched shape in another, and that behavior will affect any composited result.

In real-world workflows, designers pick the interpretation that matches the source material and the intended visual effect. Photographic elements or images with actual alpha channels are naturally suited to an interpretation based on transparency, while hand-drawn grayscale maps and gradients are naturally interpreted as tonal coverage. The property therefore guides authoring decisions for the assets used in mask-image and related mask sources. When you need crisp geometric clipping rather than a gradual mask, consider alternate approaches such as clip-path or adjusting how a mask is authored with tools that match the intended interpretation (see also mask-type for other mask semantics).

Beyond visual appearance, the interpretation can affect rendering behavior: it influences interpolation and anti‑aliasing of mask pixels, how semi‑transparent pixels are treated during composition, and in some implementations can change performance characteristics because the rendering engine may take different compositing or sampling paths. Understanding what the mask source actually represents (alpha versus tonal information) helps avoid unwanted conversions, preserve edge fidelity, and produce predictable results when layering multiple masks.