clip-path answers 'what shape should this element be cut into, with a hard edge'. CSS masking answers a more nuanced question: 'how visible should each part of this element be, on a smooth, gradual scale' — a genuinely different and complementary capability.
1Luminance: Brightness As A Visibility Map
The default masking mode reads the referenced mask image's luminance (perceived brightness, accounting for how the eye weighs different color channels) at every pixel, and maps that brightness directly to the corresponding pixel's visibility on the masked element: pure white in the mask means fully visible, pure black means fully hidden, and every gray value in between produces a proportionally partial, semi-transparent result.
This is precisely what makes a linear-gradient from black to transparent (or white to black) such a powerful mask image: it produces a smooth, continuous fade-out effect on the masked element, something clip-path's hard-edged shape boundaries fundamentally cannot express, since a pixel in clip-path is always either fully inside or fully outside the clipping region, with no partial states in between.
2Filling Complex Shapes With Any Content
Beyond gradients, any image — a complex SVG icon, a logo silhouette, a photograph used purely for its alpha channel — can serve as a mask, revealing the underlying element's actual content (a solid color, a gradient, even a video) only within the visible/bright regions of that mask shape. A common, visually striking application: filling a complex logo or icon silhouette with an animated gradient or video, producing an effect that would otherwise require pre-rendering the combination as a static image or video asset.
This technique cleanly separates 'the shape' (defined by the mask image) from 'the content' (whatever's actually being masked), letting either change independently — swap the gradient colors without touching the icon shape, or swap the icon shape without touching the gradient definition.
3Compound Effects With mask-composite
Multiple mask layers can be declared together (comma-separated, similar to multiple background images), and mask-composite controls how they combine, using set-theory-like operations: add (union — visible wherever either mask is), subtract (visible where the first mask is, minus where the second is), intersect (visible only where both overlap), and exclude (visible where exactly one, but not both, masks cover).
This enables compound masking effects that would be awkward or impossible to author as a single mask image — like revealing content only in the specific overlapping region between two independently-defined shapes, a technique used for sophisticated icon effects, cutout compositions, and layered visual designs.
4Step-by-Step Breakdown
Soft, Gradual Reveal — Not Just Hard Edges. clip-path draws a hard boundary — a pixel is either fully inside the shape or fully outside it. CSS masking is more nuanced: it uses another image's grayscale luminance or alpha transparency to determine, pixel by pixel, exactly how visible each part of an element should be — enabling soft, gradual fades and edges clip-path fundamentally can't express.
Luminance Masking: Brightness Determines Visibility. By default, mask-image uses the referenced image's luminance (brightness) to determine visibility — white areas of the mask image become fully visible, black areas become fully hidden, and every gray value in between produces a proportional, partial transparency, letting a gradient mask image produce a smooth, soft-edged fade.
Luminance Masking. In a luminance-based CSS mask, what does a mid-gray area of the mask image produce on the masked element?
- →Full visibility, identical to white
- →Partial, proportional visibility somewhere between fully hidden and fully visible
- →No effect at all — only pure black and white matter
Using An Actual Image As A Complex Mask Shape. Beyond simple gradients, any image — a PNG with a complex silhouette, an SVG icon — can serve as a mask, revealing the underlying element only through the shape of the mask image's opaque/bright regions, a technique commonly used to fill a complex icon or logo shape with a gradient, photo, or video.
Filling A Shape With Content. What visual effect does masking a gradient-filled div with an SVG star icon achieve?
- →Only a thin outline of the star shape, with no fill
- →The gradient becomes visible only within the star shape's silhouette, effectively 'filling' the icon shape with the gradient
- →No visible effect — masks only work with grayscale images
Combining Multiple Masks And mask-composite. Multiple mask layers can be combined with mask-composite operations (add, subtract, intersect, exclude) similar to how multiple background images layer — letting you build compound masking effects, like revealing an element only in the region where two different mask shapes overlap, or everywhere except where they overlap.
mask-composite Operations. What does mask-composite: intersect produce when combining two mask shapes?
- →Visibility wherever either shape is present
- →Visibility only in the region where both shapes overlap simultaneously
- →Visibility everywhere except both shapes
CSS Masking Mastered. You now understand luminance-based masking for smooth, gradual fades, how any image can serve as a mask shape to fill complex silhouettes with gradients or other content, and how mask-composite combines multiple masks with set-like operations for compound visibility effects.
Stop A Mask Image From Tiling. Like background-repeat, mask-repeat controls whether a mask image tiles across an element.
Level Up 🚀
Advanced cheat sheets, SEO tricks, and interview prep for this topic.
Browser Support
Fully supported.
Fully supported.
Fully supported.
Fully supported.
Accessibility (A11y)
1Masked-Away Content Should Be Verified As Genuinely Decorative, Not Accidentally Hiding Meaningful Information
Since masking can partially or fully hide content visually while it may still exist in the DOM, verify that anything masked to low or zero visibility isn't content a sighted user actually needs to perceive.
2Text Content Should Rarely Be Masked In Ways That Reduce Its Legibility Below Accessible Contrast Levels
A gradient-faded mask applied to text can produce portions with insufficient contrast against the background — reserve heavy masking effects for decorative or non-critical text, not primary readable content.
SEO Implications
- 1
CSS Masking Replaces Pre-Composited Image/Video Assets With A Combinable, Editable Native Technique
Filling a shape with a gradient or video via mask-image avoids needing a separate, harder-to-update pre-rendered asset for the same visual effect, reducing both page weight and future maintenance cost.
- 2
Gradual, Masked Reveals Can Reduce Perceived Layout Harshness Compared To Abrupt clip-path Cuts
For content where a soft, gradual visual transition is more appropriate than a hard edge, masking can contribute to a more polished perceived design quality, an indirect but real engagement factor.
Best Practices
Use Luminance Gradient Masks Specifically When A Smooth, Gradual Fade Is Needed, Not Just Any Non-Rectangular Shape
If a hard edge is genuinely what's needed, clip-path is simpler and more direct; reserve masking for cases where the gradual, proportional visibility behavior is actually the point.
Keep Mask Shape And Masked Content As Independently-Editable Concerns Where Practical
Structuring a mask-image (shape) separately from a background or content layer (what's being revealed) keeps both easier to update independently as a design evolves.
Frequent Bugs
A mask image applied via mask-image produces no visible fade effect, appearing as a hard-edged shape instead.
Check whether the mask image itself has genuine gradient/grayscale gradation — a mask image with only pure black and white regions (no gray) will produce hard edges, not a smooth fade, by design.
Two mask layers combined with mask-composite don't produce the expected compound shape.
Verify the chosen composite operation (add/subtract/intersect/exclude) actually matches the intended visual logic — these behave like distinct set operations, easy to mix up.
Real-World Examples
A Gradient-Filled Logo Icon
A brand logo SVG used as a mask shape, revealing an animated gradient background only within the logo's silhouette, producing a dynamic, colorful icon effect without any pre-rendered image asset.
.logo-fill {
mask-image: url('logo.svg');
mask-size: contain;
background: linear-gradient(45deg, #FF0099, #00F0FF, #CCFF00);
background-size: 200% 200%;
animation: gradient-shift 3s ease infinite;
}