CSS Reference Property

mask-composite

The mask-composite property is used to specify how a mask layer image is composited with other mask layer images beneath it (or behind it).

Compositing describes how shapes of different elements are combined into a single image. When multiple mask layer images are applied to an element, they are composited into one mask that eventually defines which portions of the element are visible and which aren’t. (See the Values section below for a visual explanation.)

The mask layer image to which to which the mask-composite value is applied to is referred to as the source, and all mask layers below it (with the corresponding compositing operators applied) are referred to as the destination.

All mask layers below the current mask layer must be composited before applying the compositing operation for the current mask layer. And mask layers must not composite with the element’s content or the content behind the element, instead they must act as if they are rendered into an isolated group.

Each keyword value of mask-composite represents a Porter-Duff compositing operator which defines the compositing operation used on the current mask layer with the mask layers below it.

The number of composite operation values is usually one less than the number of available mask layer images. See the Official Syntax Notes section below for details.

Official Syntax

  • Syntax:

    mask-composite: <compositing-operator>#
    
    /* where */
    
    <mask-composite> = add | subtract | intersect | exclude
                           
  • Initial: add
  • 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 image compositing operations. The list of mask image compositing operations is comma-separated.

The number of values needed for mask-composite is one value less than the number of mask images specified using mask-image. For example, if you have two images, you need only one mask-composite value; this value is used to specify how the first image is composited with the second one beneath it. (Remember, the first image specified is placed on top of the ones specified after it.)

If you have three images, you would need only two values. The first value is used to perform the composite operation of the second image with the third one, and the second value is used to perform the composite operation of the first mask image with the result obtained from the first operation. And so on for any number of mask layer images.

Values

Consider the following two mask layer images shown in the following images.

square-mask
A square-shaped mask image.

circle-mask
A circle-shaped mask image.

In what follows, consider the two masks applied to the same element. The two masks form two mask layers on the element, and are applied to the element using the mask-image property as follows:

mask-image: url(circle.svg), url(square.svg);
                

The square mask layer is below the circle mask layer. That means the circle is closer to the user than the square, and it will be composited with the square using the following composite operations. The circle is the source, and the square is the destination.

Each composite operation value has the following meanings:

add
The source is placed over the destination. This is equivalent to the Porter-Duff compositing operator source over.
add-composite-operation
The result of applying the add composite operation to the two mask images. The circle is painted on top of the square. add uses the combination of the two masks laid on top of each other.
subtract
The source is placed, where it falls outside of the destination. This is equivalent to the Porter-Duff compositing operator source out.
subtract-composite-operation
The result of applying the subtract composite operation to the two mask images. intersect uses portions of the circle that do not overlap with the square.
intersect
The parts of source that overlap the destination, replace the destination. This is equivalent to the Porter-Duff compositing operator source in.
intersect-composite-operation
The result of applying the intersect composite operation to the two mask images. intersect uses portions of the circle that overlap with the square.
exclude
The non-overlapping regions of source and destination are combined. This is equivalent to the Porter-Duff compositing operator XOR.
exclude-composite-operation
The result of applying the exclude composite operation to the two mask images. exclude uses portions of the circle and the square that do not overlap.

Notes

If there is no further mask layer, the compositing operator must be ignored. All mask layers below the current mask layer must be composited before applying the compositing operation for the current mask layer.

Note that at the time of writing of this entry (June, 2014) WebKit and Blink support the mask-composite property with values other than the ones listed above. As a matter of fact, the Porter-Duff operation keywords are supported instead of the keywords listed here. Which means that instead of add, subtract, intersect, and exclude, the respective values source-over, source-out, source-in, and XOR are implemented. The old keywords will, however, be replaced with the new ones in the future.

Examples

The following example specifies two mask layer images using the mask-image property, positions them using the mask-position property, sets them not to be repeated using mask-repeat, and then sets the composite operation using mask-composite.

img {
    mask-image: url(mask-image.png), url(splatter.png);
    mask-position: center center, bottom right;
    mask-repeat: no-repeat, no-repeat;
    mask-size: 350px 350px, 350px 350px;
    mask-composite: exclude; /* XOR */
}
                

See the live demo below for a live example.

Live Demo

In the following demo, the following two alpha mask images are used:

masks
The two masks used in the live demo. The one on the left is positioned beneath the one on the right.

They’re positioned so that they partially overlap. Try changing the value of the mask-composite property to see the final mask change, therefore changing the parts of the element that are visible through it.

Note that the demo uses the non-standard keywords (as mentioned in the Values section) because the new ones are not implemented in any browser yet. The following demo should work in WebKit and Blink based browsers.

View this demo on the Codrops Playground

The following is the result of applying the exclude value in the above demo. The image is visible only in the areas where the two masks do not intersect. The area where they do intersect is removed from the final mask based on the exclude operation.

exclude
The result of applying the exclude value in the live demo.

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

  • No
  • 53
  • No
  • No
  • No

Mobile / Tablet

  • No
  • No
  • No
  • No
  • 54

* 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:37 pm by Mary Lou

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