CSS Reference Property

mask

The mask property is a shorthand property for setting all mask properties. It accepts one or more comma-separated values, where each value corresponds to a mask layer:

mask: <mask-layer>#
                

Each layer specifies the mask-image, mask-mode, mask-position, mask-size, mask-repeat, mask-origin, mask-clip, and mask-composite properties for that layer:

<mask-layer> = <mask-reference> <masking-mode>? || <position> [ / <bg-size> ]? ||
    <repeat-style> || <geometry-box> || [ <geometry-box> | no-clip ] || <compositing-operator>
                

For each layer the shorthand first sets the corresponding layer of each property to that property’s initial value, then assigns any explicit values specified for this layer in the declaration.

In other words, the mask shorthand property assigns explicit given values and sets missing properties to their initial values. As a matter of fact, the mask shorthand also resets mask-border to its initial value. It is therefore recommended that you use the mask shorthand, rather than other shorthands or the individual properties, to override any mask settings earlier in the cascade. This will ensure that mask-border has also been reset to allow the new styles to take effect.

Hence, if you use the mask shorthand and only specify some of the mask properties and not all of them, then the other mask properties will be set to their initial values in the shorthand property.

Both the mask-clip and mask-origin take a <geometry-box> value; but what if only one box value is specified in the shorthand property?

If one <geometry-box> value is present then it sets both mask-origin and mask-clip to that value. If two values are present, then the first sets mask-origin and the second mask-clip.

The used value of the properties mask-repeat, mask-position, mask-clip, mask-origin and mask-size must have no effect if <mask-reference> (in mask-image) references a <mask> element. In this case the element defines position, sizing and clipping of the mask layer image.

Official Syntax

  • Syntax:

    mask = <mask-layer>#
    
    /* where */
    <mask-layer> = <mask-reference> <masking-mode>? || <position> [ / <bg-size> ]? ||
        <repeat-style> || <geometry-box> || [ <geometry-box> | no-clip ] || <compositing-operator>
                           
  • Initial: The concatenation of the initial values of the individual properties
  • Applies To: All elements. In SVG, it applies to container elements excluding the <defs> element and all graphics elements
  • Animatable: Only the mask-position and mask-size properties are animatable

Values

<‘mask-reference’>
See mask-image entry for a list of possible values.
<‘masking-mode’>
See mask-mode entry for a list of possible values.
<‘position’>
See mask-position entry for a list of possible values.
<‘bg-size’>
See mask-size entry for a list of possible values.
<‘repeat-style’>
See mask-repeat entry for a list of possible values.
<‘geometry-box’>
See mask-origin entry or the mask-clip entry for a list of possible values.
<‘compositing-operator’>
See mask-composite entry for a list of possible values.

Notes

The values of the individual mask properties in the mask shorthand can be shuffled (reordered). Only requirement is that the mask-size property must be specified after the mask-position property, and they must be separated with the ‘/’ character. You cannot specify the mask size in the shorthand property unless you also specify the mask position, otherwise the declaration is invalid.

Examples

The following example applies a mask to an element using the mask shorthand property:

.element {
    mask: url(mask.png) luminance 50% 50% / contain no-repeat border-box;
}
                

The following example defines two mask layers to be used as a mask on an element using the mask shorthand property:

img {
    mask: url(my-mask.png) alpha center no-repeat exclude, linear-gradient(black, transparent);
}
                

Where the mask layer does not specify the longhand properties, they are set to their initial values.

Note that the value of the mask-composite property is used on the first mask layer declaration not the second; this is because the first layer is the one that is composited on top of the second, and the second does not get composited with anything because there is no layer beneath it. See the mask-composite property entry for more information.

The following example applies a mask to an element:

.el {
    mask: url(the-mask.png) alpha center center no-repeat;
}
                

The above shorthand is equivalent to:

.el {
    mask-image: url(the-mask.png);
    mask-mode: alpha;
    mask-position: center center;
    mask-size: auto;                /* initial value */
    mask-repeat: no-repeat;
    mask-origin: border-box;        /* initial value */
    mask-clip: border-box;          /* initial value */
    mask-composite: add;            /* initial value */
}
                

The mask declaration here also resets the mask-border property.

Live Demo

The following example applies a mask to an element using two mask layers.

Note that at the time of writing of this entry (June, 2014) the mask property does not work when a mask-composite value is used in the shorthand. If you want to specify a composite operation, use the mask-composite property.

View this demo on the Codrops Playground

Browser 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

  • 4*
  • 3.5
  • No
  • 15*
  • 4*

Mobile / Tablet

  • 3.2*
  • 2.1*
  • 37*
  • 57*
  • 52

* denotes prefix required.

  • Supported:
  • Yes
  • No
  • Partially
  • Polyfill

Stats from caniuse.com

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.

Further Reading

Written by

Last updated December 11, 2016 at 10:35 pm by Mary Lou

Do you have a suggestion, question or want to contribute? Submit an issue.