The mask-image property sets the image used as a mask layer. Opaque parts of the mask keep the element visible; transparent parts hide it. Gradients and url() images both work.
It is not inherited. The initial value is none. Pair it with mask-mode, mask-size, and mask-repeat when you need more control.
Standard-track · Baseline Widely available.
Not deprecated. Unprefixed mask-image is Baseline since December 2023. Keep -webkit-mask-image for older WebKit and Chromium. SVG <mask> sources often use luminance; set mask-mode when alpha-only masking is required.
Set the photo as background. That is the content being masked.
Point mask-image at a PNG. Opaque pixels of the PNG reveal the photo.
Size and center it.contain + no-repeat keep one clean shape.
Serve over HTTP(S).file:// mask URLs fail CORS and look fully hidden.
Edge Cases & Pitfalls
Most “invisible” masks come from bad URLs, tiling, or luminance rules.
cors
Local file:// masks fail
Mask images must load over HTTP or HTTPS. A missing or blocked URL becomes a transparent black layer and hides everything.
repeat
Image masks tile by default
Without mask-repeat: no-repeat and a sensible mask-size, a small PNG can repeat across the box.
luminance
SVG <mask> uses luminance
White shows, black hides. Colors matter unless you set mask-mode: alpha.
prefix
Older engines need -webkit-
Write both -webkit-mask-image and mask-image when supporting browsers before the unprefixed Baseline.
Compatibility
Browser Support
mask-image is a browser CSS property. Node.js, Deno, and Bun do not apply it.
✓ Baseline · Widely available since Dec 2023
mask-image
Unprefixed: Chrome 120+, Edge 120+, Firefox 53+, Safari 15.4+, Opera 106+. Prefixed -webkit-mask-image works in much older WebKit/Blink. Internet Explorer has no support.
97%Global reach
Google Chrome120+
Full support
Mozilla Firefox53+
Full support
Apple Safari15.4+
Full support
Microsoft Edge120+
Full support
Opera106+
Full support
Samsung Internet25.0+
Full support
Internet ExplorerNo support
Not supported
mask-imageWidely supported
Bottom line: Safe for modern sites. Keep -webkit-mask-image for older Safari and Chromium. Skip Internet Explorer. This is browser layout CSS, not a server runtime API.
Remember
Key Takeaways
Role: hide parts of an element using an image or gradient mask.
One line:mask-image is a stencil — use gradients or images to show and hide parts of a box.
Frequently Asked Questions
It sets an image or gradient used as a mask. Opaque areas of the mask keep the element visible; transparent areas hide it.
The initial value is none. No mask is applied and the element stays fully visible.
clip-path cuts a hard geometric shape. mask-image uses alpha (and sometimes luminance) from an image or gradient, so fades and soft edges are easy.
Yes. linear-gradient() and radial-gradient() are common masks for fades and soft circles without extra image files.
Unprefixed mask-image is Baseline. Keep -webkit-mask-image as well when you need older WebKit and Chromium engines.
It is Baseline and widely available. Unprefixed support: Chrome 120+, Edge 120+, Firefox 53+, Safari 15.4+. Prefixed support is older. Internet Explorer does not support it. It is a browser CSS property, not a Node.js feature.