The mask-image property is used to specify one or more comma-separated images to be used as mask layers on an element.
It can also reference SVG <mask> elements, and then the contents of the mask are used as a mask layer image. The mask can be applied to HTML and/or SVG elements.
The mask of an element can have multiple layers. The number of layers is determined by the number of comma-separated values for the mask-image property.
What is Masking?
Masking is a graphical operation used to partially or fully hide portions of an object or element. The effect of applying a mask to a graphical object is as if the graphical object will be painted onto the background through the mask, thus completely or partially masking out parts of the graphical object.
The mask-image property references one or more mask references (can be CSS images and/or SVG mask elements). Each mask reference acts as a mask layer. The type of a mask layer image can be either alpha or luminance. To specify the type of a mask, you can use the mask-mode property (for CSS images) and the mask-type property (for SVG <mask>s).
Other properties allow you to control how you size, position, and tile a mask layer image. See the Related Properties section below for a list of related masking properties that you should check out.
If more than one mask layer image is specified, they are layered similar to how background images are layered: when more than one mask layer image is set, each of the images is sized, positioned, and tiled according to the corresponding value in the other mask properties. The mask layer images are then stacked on top of each other, with the first specified being on top of the others.
All mask layer images are then transformed to alpha masks (if necessary see here) and combined by compositing taking the compositing operators specified by mask-composite property into account.
Trivia & Notes
An element can also be masked with mask-border-source. See the mask-border-source property entry for the interaction of that property with mask-image.
Official Syntax
-
Syntax:
mask-image: <mask-reference># /* where */ <mask-reference> = none | <image> | <mask-source> /* and where */ <mask-source> = <url> /* and the URL points to an SVG <mask> element */ - Initial: none
- Applies To: All elements. In SVG, it applies to container elements without the <defs> element and all graphics elements
- Animatable: no
Notes
The hash tag (#) indicates that the property takes any number of mask references. The list of masks is comma-separated.
When multiple images are specified, the images are stacked on top of each other, with the first specified being on top of the others, so it is drawn as if it is the closest to the user.
Values
- none
-
A value of
nonecounts as a transparent black image layer. - <url>
-
A
<url>that references an SVG<mask>element or a CSS image. - <image>
-
An
<image>that is to be used as a mask. See the<image>entry for a list of possible values.
Notes
A computed value of other than none results in the creation of a stacking context the same way that the CSS opacity property does.
A mask reference that is an empty image (zero width or zero height), that fails to download, is not a reference to a <mask> element, is non-existent, or that cannot be displayed (e.g. because it is not in a supported image format) is ignored. It still counts as an image layer of transparent black.
Note that a value of none in a list of mask references may influence the masking operation depending on the used compositing operator specified by mask-composite.
Examples
The following is an example referencing an image (a PNG image) to be used as a mask.
img {
/* ... */
mask-image: url(splash.png);
};
The following is an example of using a CSS gradient as a mask image. A gradient is an image and so it can be used as a mask image.
img {
mask-image: linear-gradient(black 0%, transparent 100%);
}
The following is an example referencing an SVG <mask> element to be used as a mask. The SVG mask in this example is a gradient. The following is the CSS code followed by the markup containing the SVG mask.
.element {
/* ... */
mask-image: url(#gradient-mask);
}
<!DOCTYPE html>
<html>
<head></head>
<body>
<svg>
<mask id="gradient-mask">
<linearGradient gradientUnits="userSpaceOnUse" x1="319.5005" y1="400.5" x2="319.5005" y2="0.5005">
<stop offset="0" style="stop-color:#FFFFFF"/>
<stop offset="0.0083" style="stop-color:#F9F9F9"/>
<stop offset="0.0835" style="stop-color:#C7C7C7"/>
<stop offset="0.1641" style="stop-color:#999999"/>
<stop offset="0.2484" style="stop-color:#717171"/>
<stop offset="0.3373" style="stop-color:#505050"/>
<stop offset="0.432" style="stop-color:#353535"/>
<stop offset="0.5348" style="stop-color:#202020"/>
<stop offset="0.6496" style="stop-color:#111111"/>
<stop offset="0.786" style="stop-color:#090909"/>
<stop offset="1" style="stop-color:#060606"/>
<stop offset="1" style="stop-color:#2F2F2F"/>
<stop offset="1" style="stop-color:#252525"/>
<stop offset="1" style="stop-color:#141414"/>
<stop offset="1" style="stop-color:#090909"/>
<stop offset="1" style="stop-color:#020202"/>
<stop offset="1" style="stop-color:#000000"/>
</linearGradient>
</mask>
</svg>
</body>
</html>
The following is an example referencing two images to be used as mask layer images, and uses the other mask properties to position and tile them:
.el {
mask-image: url(mask-image.png), linear-gradient(black, transparent);
mask-position: center, top left;
mask-repeat: no-repeat, no-repeat;
}
Live Demo
The following is a live demo of applying a mask to an image. The image and the mask used are shown in the following image. The mask is an alpha mask; which means that the black areas will be the areas that the element (image in our case) will show through.
View this demo on the Codrops Playground
The following is a live demo using a CSS gradient as a mask.
View this demo on the Codrops PlaygroundBrowser Support
CSS Masks
Method of displaying part of an element, using a selected image as a mask
W3C Candidate Recommendation
Supported from the following versions:
Desktop
- 120
- 53
- No
- 106
- 15
Mobile / Tablet
- 15
- 130
- No
- 130
- 130
Notes
This module, as you can see in the support table above, hasn’t been fully implemented in all browsers, so you’re probably not going to be able to use all features even in browsers that have implemented certain properties (for the time being).
In the meantime, you can check out this open source feature support table by Alan Greenblatt on GitHub. The purpose of this table is to provide some insight into what the current state of affairs is with various browser implementations of CSS Clipping and Masking features.
