CSS Masks: Browser Support, Properties, Known Issues

What are CSS Masks?

CSS Masks are a W3C feature from the CSS Masking Module Level 1 that hides part of an element through the alpha or luminance channel of a mask source. The mask shorthand and its longhands accept PNG images, SVG mask elements, and CSS gradients as that source.

Which browsers support CSS Masks?

Every modern desktop and mobile browser supports the unprefixed mask property, while older Chromium, Safari, and Samsung Internet builds need the -webkit-mask-image prefix and Internet Explorer never added support. Global coverage reaches roughly 96% when partial, prefixed support is counted.

What are the key CSS mask properties?

The mask shorthand rolls up eight longhand properties from the CSS Masking Module Level 1. Setting the shorthand resets every longhand it covers, so reach for the longhand when you only want to change one piece.

• mask-image: Sets the source of the mask. Accepts a url() to a PNG or SVG file, a url(#id) to an inline SVG mask element, or a CSS gradient like linear-gradient() or radial-gradient().
• mask-mode: Picks how the source is read, with values alpha, luminance, or match-source. Alpha uses transparency to hide and reveal; luminance uses brightness, which matches legacy SVG mask behavior.
• mask-clip: Defines the painting area for the mask, with values border-box, padding-box, content-box, fill-box, stroke-box, view-box, or no-clip.
• mask-origin: Sets the origin point the mask is positioned from, using the same box-keyword values as mask-clip.
• mask-size: Sizes the mask source, with values auto, contain, cover, or explicit length and percentage values.
• mask-repeat: Controls tiling, with values repeat, repeat-x, repeat-y, space, round, or no-repeat.
• mask-position: Places the mask source inside the origin box, with the same syntax as background-position.
• mask-composite: Combines stacked masks, with values add, subtract, intersect, and exclude. Use it when you pass multiple comma-separated mask images and want them to interact.

A separate mask-border shorthand and its longhands cover image-based border masks, but support for mask-border lags behind the main mask property and currently ships only in WebKit and Firefox.

How do you use CSS Masks?

Pick a mask source, point mask-image at it, and pair the unprefixed declaration with the -webkit-mask-image fallback. The steps below cover the common image, gradient, and SVG patterns in one pass.

• Pick a mask source: Decide between a raster image (PNG with transparent regions), a CSS gradient (linear, radial, or conic), or an inline SVG mask element referenced by id.
• Set mask-image with the prefix: Write -webkit-mask-image first, then mask-image right below with the same value, so older Blink and WebKit builds still match the rule.
• Control sizing and tiling: Add mask-size: contain or mask-size: cover to fit the source to the element, and mask-repeat: no-repeat unless you want the source tiled.
• Switch mask-mode if needed: Leave mask-mode at match-source for most cases. Set mask-mode: alpha for PNGs that rely on transparency or mask-mode: luminance for grayscale luminance masks.
• Test the prefixed and unprefixed paths: Open the page in Chrome 120+, Safari 15.4+, and one older Safari or Samsung Internet build to confirm both code paths render the mask correctly.

/* Use a PNG or SVG image as the mask source. */
.image {
    -webkit-mask-image: url(shape.svg);
            mask-image: url(shape.svg);
    -webkit-mask-size: contain;
            mask-size: contain;
    -webkit-mask-repeat: no-repeat;
            mask-repeat: no-repeat;
}

/* Fade the bottom of an image with a CSS gradient. */
.fade {
    -webkit-mask-image: linear-gradient(to bottom, black 60%, transparent 100%);
            mask-image: linear-gradient(to bottom, black 60%, transparent 100%);
}

/* Reference an inline SVG <mask> element by its id. */
.svg-mask {
    -webkit-mask-image: url(#star);
            mask-image: url(#star);
    -webkit-mask-mode: alpha;
            mask-mode: alpha;
}

The three rules above cover image, gradient, and inline-SVG mask sources. Drop them into a stylesheet, attach the matching class to an element with visible content, and the mask appears on every browser that supports either the prefixed or unprefixed declaration.

What are the known issues with CSS Masks?

CSS Masks have a few sharp edges that show up only when you ship to production across browsers. Plan around these before you replace static PNG cutouts with a mask rule.

• The -webkit-mask-image prefix is still required for older Blink and WebKit: Chrome 4 to 119, Edge 79 to 119, Safari 4 to 15.3, and Samsung Internet 4 to 24 only recognize the prefixed property. Drop the prefix and the mask disappears on every device that has not updated past those builds.
• mask-composite values differ between Blink and WebKit: WebKit historically used keywords like source-over, source-in, and source-out, while the W3C spec and Blink ship add, subtract, intersect, and exclude. Use the spec keywords on Chrome 120+ and Safari 15.4+, and fall back to the WebKit keywords for the prefixed -webkit-mask-composite path.
• SVG mask references behave differently from image and gradient masks: Firefox accepts mask: url(#id) all the way back to Firefox 3.5, but image and gradient sources only work from Firefox 53. If your mask source is an inline SVG mask element, you get broader Firefox coverage than image or gradient masks.
• mask-mode default changed across versions: Older WebKit builds default to alpha masking, while Firefox and current spec implementations default to match-source. Set mask-mode explicitly when you need consistent behavior, especially for SVG mask sources where match-source resolves to luminance.
• The mask-border shorthand lags the main mask: Only Safari and Firefox ship parts of mask-border under the unprefixed name. Treat mask-border as progressive enhancement and avoid it on Blink-only flows.
• In my experience, the prefix gap catches more teams than any other mask quirk: a polished mask design ships, looks perfect in current Chrome and Safari, and silently drops on a two-year-old iPhone or Galaxy because the unprefixed declaration is the only one in the stylesheet, so always include both lines and run the page through a real Safari 15 device before release.

Citations

All CSS Masks version numbers and platform notes in this guide come from these primary sources:

• MDN mask CSS property: developer.mozilla.org/en-US/docs/Web/CSS/mask
• MDN mask-image CSS property: developer.mozilla.org/en-US/docs/Web/CSS/mask-image
• MDN CSS Masking module overview: developer.mozilla.org/en-US/docs/Web/CSS/CSS_masking
• MDN Introduction to CSS masking: developer.mozilla.org/en-US/docs/Web/CSS/Guides/Masking/Introduction
• W3C CSS Masking Module Level 1: drafts.csswg.org/css-masking-1
• WebKit blog, CSS Masks: webkit.org/blog/3074/css-masks
• web.dev, Apply effects to images with the CSS mask-image property: web.dev/articles/css-masking
• MDN mask-mode CSS property: developer.mozilla.org/en-US/docs/Web/CSS/mask-mode
• MDN mask-composite CSS property: developer.mozilla.org/en-US/docs/Web/CSS/mask-composite
• MDN mask-border CSS property: developer.mozilla.org/en-US/docs/Web/CSS/mask-border