CSS Mask Table
| Piece | What it does | Field note |
|---|---|---|
mask-image | The alpha stencil | Where the mask is OPAQUE the element shows - transparency cuts |
linear-gradient as mask | Fade-out edges | The classic: mask-image: linear-gradient(black, transparent) |
mask-size / position / repeat | Same box model as bg | All the background longhands exist for masks too |
mask-composite | Combine masks | add/subtract/intersect/exclude - multi-stencil logic |
mask vs clip-path | Bitmap vs geometry | clip-path cuts a SHAPE; mask multiplies ALPHA per pixel |
-webkit-mask prefix | The compat tax | Safari needed the prefix for years - autoprefixers remember |
icon recolor trick | mask-image: url(icon.svg) | currentColor-tinted icons: mask an element, set color |
mask-mode | Luminance vs alpha | SVG luminance masks - Photoshop-style blending arrives |
A mask is an ALPHA STENCIL: wherever the mask image is opaque the element shows, wherever transparent the element is cut - so the fade-out-edge effect is one linear-gradient in mask-image, and every mask longhand (size, position, repeat) mirrors the background box model exactly.
Bottom line: the distinction from clip-path is bitmap versus geometry - clip-path cuts a hard SHAPE, a mask multiplies ALPHA per pixel (gradients, images, soft edges). And the icon-recolor trick is the everyday winner: mask-image: url(icon.svg) with background: currentColor tints monochrome icons with one property.
The honest part: Safari required the -webkit-mask prefix for years, so production masks ship both forms - autoprefixers remember, but hand-written CSS in code review should too. The un-prefixed property is now standard; the prefix is compatibility debris that still matters on older Safari.
How to use
- Fade an edge: mask-image: linear-gradient(to bottom, black 70%, transparent) - the image dissolves toward its bottom, one declaration.
- Recolor an icon: .icon { mask-image: url(icon.svg); mask-size: contain; background-color: currentColor; } - one SVG, every text color, no duplicate assets.
- Combine stencils: mask-composite: intersect with two mask layers - show only where BOTH masks are opaque (a gradient fade inside a circle).
Frequently asked questions
How does a mask actually decide which pixels show?
Per-pixel alpha multiplication. The mask image is stretched/positioned like a background, then for every pixel of the element, the mask's ALPHA channel scales the element's own alpha - opaque mask areas show the element fully, 50% gray mask areas show it at 50%, transparent areas cut it completely. (mask-mode can switch to using LUMINANCE instead - white shows, black hides - which is how SVG luminance masks and Photoshop-style transfers arrive.) The mental model: the mask is a stencil held over the element, and soft stencil edges produce soft element edges - which is exactly why gradients make the best masks.
When is a mask the right tool versus clip-path?
Shape versus image. clip-path cuts a hard geometric silhouette - a circle, polygon or path with crisp edges and no partial transparency; it cannot produce a soft gradient fade because it has no per-pixel alpha. A mask is an IMAGE operating per-pixel - it produces fades, soft vignettes, texture holes and any grayscale transition. The decision: hard shape = clip-path (simpler, cheaper, animatable as a shape); anything with softness, imagery or per-pixel variation = mask. The two also compose with different mental models: clip-path changes the element's visible geometry; a mask filters its pixels - visible in how they respond to animations of their own.
Why do masks still need the -webkit- prefix in 2026?
Safari's long standards lag. The mask properties existed as -webkit-mask for a decade before the unprefixed standard was broadly implemented, and older-but-supported Safari versions still only honor the prefixed form. Production masks therefore ship both: -webkit-mask-image first, mask-image second - which is exactly the kind of duplication autoprefixers exist to manage, so the practical rule is 'never hand-write a mask without the build handling prefixes, or write both lines yourself.' The prefix is compatibility debris, but it is debris that still catches real users on slightly older devices.
What makes the mask-based icon recolor better than the alternatives?
One asset, full color control. The alternatives all cost something: inline SVG lets you set fill: currentColor but bloats every HTML file with the markup; two-tone font icons need a font pipeline; duplicated SVG files per color multiply assets and cache entries. The mask approach: the icon SVG is a single cached asset used as an alpha stencil, and the ELEMENT's background-color (set to currentColor) shows through - so the icon inherits text color, follows dark/light themes, and hover states recolor it for free. The constraint is the trade: only monochrome (alpha-shaped) icons work - the mask discards the SVG's own colors, which is precisely why it can be recolored.