Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท Filters, Masks and Shapes

The mask-image property

Reference for the CSS mask-image property: use gradients, images or SVG masks to hide or fade parts of an element, with live examples and caveats.

The mask-image property sets the image used as one or more mask layers. The parts of the element that line up with opaque pixels in the mask stay visible, parts that line up with transparent pixels are hidden, and semi-transparent pixels make the element semi-transparent.

The image can be any CSS <image>: a gradient, a PNG or SVG loaded with url(), or a reference to an SVG <mask> element. It is the main longhand of the mask shorthand.

CSS
.title {
  mask-image: linear-gradient(to right, black 70%, transparent);
}

Try it

Fade out the end of a line of text
An inline SVG shape as a mask

The SVG's fill is irrelevant; only its alpha channel (shape versus empty space) matters.

Syntax

CSS
mask-image: <mask-reference>#

/* <mask-reference> = none | <image> | <mask-source> */
  • Initial value: none
  • Applies to: all elements; in SVG, container elements (except <defs>) and graphics elements
  • Inherited: no
  • Animatable: no
  • Computed value: as specified, but with any url() made absolute

Values

Value Description
none A transparent black layer: it does not mask anything.
<image> A gradient (linear-gradient(), radial-gradient(), conic-gradient()), a url() image, image-set() or element()-style image.
url(#id) A reference to an SVG <mask> element. This is a "mask source", which defaults to luminance masking.
Comma-separated list One layer per entry. The first is on top. Other mask properties take lists that line up with the images.

Usage notes

  • Alpha, not color. For ordinary images, only the alpha channel counts, so black and red are equally "visible". Use mask-mode to switch to luminance if needed.
  • Gradients are the easiest masks. A gradient from an opaque color to transparent fades an element out. To avoid a muddy-looking midpoint, keep both stops the same color (e.g. black to transparent).
  • Same-origin or CORS. An image from another origin without CORS headers can make the mask invalid, so the element is hidden entirely. Self-hosted files or data: URLs avoid this.
  • A broken or missing image is treated as none in some cases and as a hide-everything mask in others; verify in your target browsers when the image URL can fail.
  • Set the geometry too. A mask image repeats by default and uses its own size. Add mask-repeat, mask-size and mask-position for a single, scaled shape.
  • Not animatable directly. Animate the mask with a custom property inside a gradient (registered with @property) or animate mask-position and mask-size.
  • Accessibility. Faded or hidden content is still in the accessibility tree; do not mask away text that screen-reader users should not hear.

Browser support

Unprefixed mask-image works in current versions of the major browsers. Older Chromium and Safari versions only supported -webkit-mask-image; add the prefixed property if you need them.