<pre class=metadata>

Title: CSS Masking Module Level 1

Status: ED

Prepare for TR: no

Work Status: Refining

Implementation Report: https://test.csswg.org/harness/results/css-masking-1_dev/grouped/

ED: https://drafts.csswg.org/css-masking-1/

TR: https://www.w3.org/TR/css-masking-1/

Previous Version: https://www.w3.org/TR/2021/CRD-css-masking-1-20210805/

Shortname: css-masking

Level: 1

Group: csswg

Issue Tracking: GitHub https://github.com/w3c/fxtf-drafts/labels/css-masking-1

Editor: Dirk Schulze, Adobe Inc., [email protected], w3cid 51803

Editor: Brian Birtles, Mozilla Japan, [email protected], w3cid 43194

Editor: Tab Atkins Jr., Google, https://www.xanthir.com/contact/, w3cid 42199

Abstract: CSS Masking provides two means for partially or fully hiding portions of visual elements: masking and clipping.

Abstract:

Abstract: Masking describes how to use another graphical element or image as a luminance or alpha mask. Typically, rendering an element via CSS or SVG can conceptually be described as if the element, including its children, are drawn into a buffer and then that buffer is composited into the element's parent. Luminance and alpha masks influence the transparency of this buffer before the compositing stage.

Abstract:

Abstract: Clipping describes the visible region of visual elements. The

region can be described by using certain SVG graphics elements or basic shapes. Anything outside of this region is not rendered.

Test Suite: https://test.csswg.org/suites/css-masking/nightly-unstable/

Ignored Vars: trapeze.svg

WPT Path Prefix: css/css-masking/

WPT Display: closed

</pre>

<pre class=link-defaults>

spec:fill-stroke-3; type:value; text:square

spec:svg2; type:property

text:fill

text:fill-rule

text:fill-opacity

text:stroke

text:stroke-dashoffset

text:stroke-dasharray

text:stroke-opacity

text:stroke-linecap

text:stroke-miterlimit

text:stroke-linejoin

text:stroke-width

spec:svg2; type:element

text:a

text:metadata

text:path

text:text

text:title

text:script

text:style

spec:svg; type:element; text:font

spec:css-backgrounds-3; type:property;

text:border-image

text:border-image-repeat

text:border-image-slice

text:border-image-width

text:border-radius

text:border-width

spec:css-color-4; type:property

text:color

spec:css-fonts-4; type:property;

text:font-family

text:font-stretch

text:font-weight

text:font-style

text:font-size-adjust

spec:filter-effects-1; type:property;

text:flood-color

text:flood-opacity

text:lighting-color

text:color-interpolation-filters

text:filter

spec:filter-effects-1; type:element;

text:fecolormatrix

text:filter

spec:css-transforms-1; type:dfn; text:user coordinate system

spec:css-overflow-3; type:value; for:overflow; text:visible

</pre>

<pre class=anchors>

spec:svg11; for:svg;

type:element;

url:https://www.w3.org/TR/SVG11/text.html#AltGlyphDefElement; text:altGlyphDef

url:https://www.w3.org/TR/SVG11/color.html#ColorProfileElement; text:color-profile

url:https://www.w3.org/TR/SVG11/interact.html#CursorElement; text:cursor

url:https://www.w3.org/TR/SVG11/fonts.html#FontElement; text:font

url:https://www.w3.org/TR/SVG11/fonts.html#FontFaceElement; text:font-face

type:property;

url:https://www.w3.org/TR/SVG11/color.html#ColorProfileProperty; text:color-profile

url:https://www.w3.org/TR/SVG11/filters.html#EnableBackgroundProperty; text:enable-background

url:https://www.w3.org/TR/SVG11/text.html#GlyphOrientationHorizontalProperty; text:glyph-orientation-horizontal

url:https://www.w3.org/TR/SVG11/text.html#KerningProperty; text:kerning

spec:svg2; url:https://svgwg.org/svg2-draft/coords.html#ViewBoxAttribute; type:element-attr; for:svg; text:viewBox

spec:svg2; url:https://svgwg.org/svg2-draft/text.html#TermTextContentElement; type:dfn; text:text content element

spec:svg2; url:https://svgwg.org/svg2-draft/render.html#TermNeverRenderedElement; type:dfn; text:never-rendered element

</pre>

<style type="text/css">

a[data-link-type=element]::before,span[data-link-type=element]::before {

content: '<';

}

a[data-link-type=element]::after,span[data-link-type=element]::after {

content: '>';

}

</style>

# Introduction # {#intro}

<em>This section is not normative.</em>

This specification defines two different graphical operations which both fully or partly hide portions of an object: clipping and masking.

<wpt title="General tests for clipping and masking">

idlharness.html

inheritance.sub.html

</wpt>

## Clipping ## {#clipping}

A closed vector path, shape or polygon defines a so called <dfn export>clipping path</dfn>. This clipping path is a region (in the absence of anti-aliasing) where everything on the “inside” of this region is allowed to show through but everything on the outside is “clipped out” and does not appear on the canvas.

<div class="example">

<div class=figure>

<img src="images/clipping-path.svg" width="655" height="260" alt="Example Mask">

<p class=caption>A clipping path (middle) is applied on a polygon shaded with different colors (left). This results in a “clipped out” shape (right).

</div>

</div>

The 'clip-path' property can use specified basic shapes as clipping path or reference an <a element>clipPath</a> element with <a>graphics elements</a> to be used as clipping path.

Clipping <em>does</em> affect hit testing;

there are no hits outside the clip region,

only inside.

## Masking ## {#masking}

The effect of applying a mask to a graphical object is as if the graphical object will be painted onto the background through a mask, thus completely or partially masking out parts of the graphical object.

<div class="example">

<div class=figure>

<img src="images/luminance-mask.svg" width="655" height="260" alt="Example Mask">

<p class=caption>A luminance mask (middle) is applied on a shape filled with a gradient (left). This results in a masked shape (right).

</div>

</div>

Masks are applied using the 'mask-image' or 'mask-border-source' properties.

The 'mask-image' property may reference a <a element>mask</a> element. The content of the <a element>mask</a> element serves as the mask.

Alternatively, for many simple uses, the 'mask-image' property may refer directly to images to be used as mask, forgoing the need for an explicit <a element>mask</a> element. This mask can then be sized and positioned just like CSS background images using the 'mask-position', 'mask-size' and other characterizing properties.

The 'mask-border-source' property splits a mask into 9 pieces. The pieces may be sliced, scaled and stretched in various ways to fit the size of the <a>mask border image area</a>. The 'mask-border' property serves as a shorthand property for 'mask-border-source' and other characterizing properties.

The 'mask' property serves as a shorthand property for all 'mask-border' and 'mask-image' affiliated properties.

Note: While masking gives many possibilities for enhanced graphical effects and in general provides more control over the “visible portions” of the content, clipping paths can perform better and basic shapes are easier to interpolate.

Masking <em>does not</em> affect hit testing.

# Module interactions # {#placement}

This specification defines a set of CSS properties that affect the visual rendering of elements to which those properties are applied. These effects are applied after elements have been sized and positioned according to the <a href="https://www.w3.org/TR/CSS2/visuren.html" title="Visual formatting model">Visual formatting model</a> from [[!CSS21]]. Some values of these properties result in the creation of a <a>stacking context</a>. Furthermore, this specification replaces the section <a href="https://www.w3.org/TR/CSS2/visufx.html#clipping">Clipping: the clip property</a> from [[!CSS21]].

The compositing model follows the SVG compositing model [[!SVG11]]: First the element is styled under absence of filter effects, masking, clipping and opacity. Then the element and its descendants are drawn on a temporary canvas. In a last step the following effects are applied to the element in order: filter effects [[FILTER-EFFECTS]], clipping, masking and opacity.

This specification allows compositing multiple mask layers with the Porter Duff compositing operators defined in CSS Compositing and Blending [[!COMPOSITING-1]].

The term <a>object bounding box</a> follows the definition in SVG 1.1 [[!SVG11]].

<wpt>

clip/clip-filter-order.html

clip/clip-transform-order-2.html

clip/clip-transform-order.html

clip-path/clip-path-filter-order.html

</wpt>

# Values # {#values}

This specification follows the <a href="https://www.w3.org/TR/CSS21/about.html#property-defs">CSS property definition conventions</a> from [[!CSS21]]. Basic shapes are defined in CSS Shapes Module Level 1 [[!CSS-SHAPES]]. Value types not defined in these specifications are defined in CSS Values and Units Module Level 3 [[!CSS3VAL]].

In addition to the property-specific values listed in their definitions, all properties defined in this specification also accept CSS-wide keywords such as <a href="https://www.w3.org/TR/CSS21/cascade.html#value-def-inherit">inherit</a> as their property value [[!CSS3VAL]]. For readability it has not been repeated explicitly.

# Terminology # {#terminology}

Definitions of CSS properties and values in this specification are analogous to definitions in CSS Backgrounds and Borders [[!CSS3BG]]. To avoid redundancy, this specification relies on descriptions and definitions of CSS Backgrounds and Borders. The following terms in CSS Backgrounds and Borders have the following meaning in this specification:

<table class="data" id="term-matching" data-export>

<thead>

<tr>

<th>Term in CSS Masking

<th>Term in [[!CSS3BG]]

</tr>

</thead>

<tbody>

<tr>

<th><a>mask layer image</a>

<td>background images

</tr>

<tr>

<th><a>mask painting area</a>

<td><a spec="css-backgrounds-3">background painting area</a>

</tr>

<tr>

<th><dfn>mask-size</dfn>

<td>background-size

</tr>

<tr>

<th><dfn>mask-position</dfn>

<td>background-position

</tr>

<tr>

<th><a>mask positioning area</a>

<td><a spec="css-backgrounds-3">background positioning area</a>

</tr>

<tr>

<th><a>mask border image</a>

<td>border-image

</tr>

<tr>

<th><a>mask border image area</a>

<td><a spec="css-backgrounds-3">border image area</a>

</tr>

</tbody>

</table>

# Clipping Paths # {#clipping-paths}

The clipping path restricts the region to which paint can be applied, the so-called <dfn export>clipping region</dfn>. Conceptually, any parts of the drawing that lie outside of this region are not drawn. This includes any content, background, borders, text decoration, outline and visible scrolling mechanism of the element to which the clipping path is applied, and those of its descendants.

An element's ancestors may also clip portions of their content (e.g., via their own 'clip' or 'clip-path' properties and/or if their 'overflow' property is not ''visible''). What is rendered is the cumulative intersection.

If the clipping region exceeds the bounds of the UA's document window, content may be clipped to that window by the native operating environment.

A clipping path affects the rendering of an element. It does not affect the element's inherent geometry. The geometry of a clipped element (i.e. an element which references a <a element>clipPath</a> element via a 'clip-path' property, or a child of the referencing element) must remain the same as if it were not clipped.

<wpt>

clip/clip-absolute-positioned-001.html

clip/clip-absolute-positioned-002.html

clip/clip-negative-values-001.html

clip/clip-negative-values-002.html

clip/clip-negative-values-003.html

clip/clip-negative-values-004.html

clip/clip-no-clipping-001.html

clip/clip-no-clipping-002.html

clip/clip-not-absolute-positioned-001.html

clip/clip-not-absolute-positioned-002.html

clip/clip-not-absolute-positioned-003.html

clip/clip-not-absolute-positioned-004.html

clip/clip-rect-auto-001.html

clip/clip-rect-auto-002.html

clip/clip-rect-auto-003.html

clip/clip-rect-auto-004.html

clip/clip-rect-auto-005.html

clip/clip-rect-auto-006.html

clip-path/clip-path-circle-001.html

clip-path/clip-path-circle-002.html

clip-path/clip-path-circle-003.html

clip-path/clip-path-circle-004.html

clip-path/clip-path-circle-005.html

clip-path/clip-path-circle-006.html

clip-path/clip-path-circle-007.html

clip-path/clip-path-circle-008.html

clip-path/clip-path-circle-closest-corner.html

clip-path/clip-path-circle-farthest-corner.html

clip-path/clip-path-element-userSpaceOnUse-001.html

clip-path/clip-path-element-userSpaceOnUse-002.html

clip-path/clip-path-element-userSpaceOnUse-003.html

clip-path/clip-path-element-userSpaceOnUse-004.html

clip-path/clip-path-ellipse-001.html

clip-path/clip-path-ellipse-002.html

clip-path/clip-path-ellipse-003.html

clip-path/clip-path-ellipse-004.html

clip-path/clip-path-ellipse-005.html

clip-path/clip-path-ellipse-006.html

clip-path/clip-path-ellipse-007.html

clip-path/clip-path-ellipse-008.html

clip-path/clip-path-ellipse-closest-farthest-corner.html

clip-path/clip-path-filter-radius-clips.html

clip-path/clip-path-on-fixed-position-scroll.html

clip-path/clip-path-polygon-001.html

clip-path/clip-path-polygon-002.html

clip-path/clip-path-polygon-003.html

clip-path/clip-path-polygon-004.html

clip-path/clip-path-polygon-005.html

clip-path/clip-path-polygon-006.html

clip-path/clip-path-polygon-007.html

clip-path/clip-path-polygon-008.html

clip-path/clip-path-polygon-009.html

clip-path/clip-path-polygon-010.html

clip-path/clip-path-polygon-011.html

clip-path/clip-path-polygon-012.html

clip-path/clip-path-polygon-013.html

clip-path/clip-path-svg-invalidate.html

clip-path/clip-path-url-reference-change-from-empty.html

clip-path/clip-path-url-reference-change.html

clip-path/clip-path-url-reference-external.html

clip-rule/clip-rule-001.html

clip-rule/clip-rule-002.html

</wpt>

<div class=example>

Consider a shape that is clipped by a clipping path applied to an ancestor:

<pre><code highlight=svg>

&lt;g clip-path="circle()">

&lt;path id="shape" d="M0,0 L10,10, L 20,0 z"/>

&lt;/g>

</code></pre>

The shape is referenced by a <a element>use</a> element:

<pre><code highlight=svg>

&lt;use xlink:href="#shape"/>

</code></pre>

The geometry of the shape is not influenced by the circular clipping path.

</div>

By default, 'pointer-events' must not be dispatched on the clipped-out (non-visible) regions of a shape. For example, an element with a dimension of 10px to 10px which is clipped to a circle with a radius of 5px will not receive ''click'' events outside the <a>clipping region</a>.

## Clipping Shape: the 'clip-path' property ## {#the-clip-path}

<pre class=propdef>

Name: clip-path

Value: <<clip-source>> | [ <<basic-shape>> || <<geometry-box>> ] | none

Initial: none

Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a element>defs</a> element, all <a>graphics elements</a> and the <a element>use</a> element

Inherited: no

Percentages: n/a

Computed value: as specified, but with <<url>> values made absolute

Media: visual

Animation type: by computed value

</pre>

<wpt>

animations/clip-path-composition.html

animations/clip-path-geometry-box-interpolation.html

animations/clip-path-interpolation-001.html

animations/clip-path-interpolation-002.html

animations/clip-path-interpolation-shape-arc-direction-agnostic-radius.html

animations/clip-path-interpolation-shape-control-points.html

animations/clip-path-interpolation-shape.html

animations/clip-path-interpolation-xywh-rect.html

clip-path/animations/clip-path-animation-cancel.html

clip-path/animations/clip-path-animation-circle-0-percent.html

clip-path/animations/clip-path-animation-custom-property.html

clip-path/animations/clip-path-animation-custom-timing-function-reverse.html

clip-path/animations/clip-path-animation-custom-timing-function.html

clip-path/animations/clip-path-animation-ellipse-mixed-change.html

clip-path/animations/clip-path-animation-ellipse.html

clip-path/animations/clip-path-animation-ensure-keyframe-update.html

clip-path/animations/clip-path-animation-filter.html

clip-path/animations/clip-path-animation-fixed-position-rounding-error.html

clip-path/animations/clip-path-animation-fixed-position.html

clip-path/animations/clip-path-animation-font-size-inherited.html

clip-path/animations/clip-path-animation-font-size-mixed-change.html

clip-path/animations/clip-path-animation-font-size.html

clip-path/animations/clip-path-animation-forward-fill-positive-delay.html

clip-path/animations/clip-path-animation-forward-fill.html

clip-path/animations/clip-path-animation-fragmented.html

clip-path/animations/clip-path-animation-geometry-box-delay.html

clip-path/animations/clip-path-animation-incompatible-shapes1.html

clip-path/animations/clip-path-animation-incompatible-shapes2.html

clip-path/animations/clip-path-animation-inherit.html

clip-path/animations/clip-path-animation-initial.html

clip-path/animations/clip-path-animation-inset-50-percent.html

clip-path/animations/clip-path-animation-missing-0-percent.html

clip-path/animations/clip-path-animation-mixed-calc.html

clip-path/animations/clip-path-animation-mixed-interpolation.html

clip-path/animations/clip-path-animation-non-keyframe-timing-function.html

clip-path/animations/clip-path-animation-none.html

clip-path/animations/clip-path-animation-overflow.html

clip-path/animations/clip-path-animation-path.html

clip-path/animations/clip-path-animation-polygon-mixed-change.html

clip-path/animations/clip-path-animation-polygon.html

clip-path/animations/clip-path-animation-reference-delay.html

clip-path/animations/clip-path-animation-retarget.html

clip-path/animations/clip-path-animation-revert-layer.html

clip-path/animations/clip-path-animation-revert.html

clip-path/animations/clip-path-animation-set-currenttime-forward-finish.html

clip-path/animations/clip-path-animation-set-currenttime-negative.html

clip-path/animations/clip-path-animation-set-duration-animation-finish.html

clip-path/animations/clip-path-animation-set-effect.html

clip-path/animations/clip-path-animation-start-time.html

clip-path/animations/clip-path-animation-svg-zoom.html

clip-path/animations/clip-path-animation-svg.html

clip-path/animations/clip-path-animation-three-keyframes1.html

clip-path/animations/clip-path-animation-three-keyframes2.html

clip-path/animations/clip-path-animation-unset.html

clip-path/animations/clip-path-animation-zero-duration.html

clip-path/animations/clip-path-animation-zoom.html

clip-path/animations/clip-path-animation.html

clip-path/animations/clip-path-interpolation-discrete.html

clip-path/animations/clip-path-path-interpolation-001.html

clip-path/animations/clip-path-path-interpolation-002.html

clip-path/animations/clip-path-path-interpolation-with-zoom.html

clip-path/animations/clip-path-rect-interpolation-001.html

clip-path/animations/clip-path-shape-interpolation-001.html

clip-path/animations/clip-path-shape-interpolation-002.html

clip-path/animations/clip-path-shape-interpolation-003.html

clip-path/animations/clip-path-shape-interpolation-004.html

clip-path/animations/clip-path-transition-allow-discrete.html

clip-path/animations/clip-path-transition-crash.html

clip-path/animations/clip-path-transition-custom-timing-function.html

clip-path/animations/clip-path-transition.html

clip-path/animations/clip-path-xywh-interpolation-001.html

clip-path/animations/two-clip-path-animation-diff-length1.html

clip-path/animations/two-clip-path-animation-diff-length2.html

clip-path/animations/two-clip-path-animation-diff-length3.html

clip-path/animations/two-clip-path-animation-diff-length4.html

clip-path/clip-path-blending-offset.html

clip-path/clip-path-borderBox-1a.html

clip-path/clip-path-borderBox-1b.html

clip-path/clip-path-borderBox-1c.html

clip-path/clip-path-borderBox-1d.html

clip-path/clip-path-borderBox-1e.html

clip-path/clip-path-columns-shape-001.html

clip-path/clip-path-columns-shape-002.html

clip-path/clip-path-contentBox-1a.html

clip-path/clip-path-contentBox-1b.html

clip-path/clip-path-contentBox-1c.html

clip-path/clip-path-contentBox-1d.html

clip-path/clip-path-contentBox-1e.html

clip-path/clip-path-descendant-text-mutated-001.html

clip-path/clip-path-document-element-will-change.html

clip-path/clip-path-document-element.html

clip-path/clip-path-fillBox-1a.html

clip-path/clip-path-fillBox-1b.html

clip-path/clip-path-fixed-nested.html

clip-path/clip-path-fixed-scroll.html

clip-path/clip-path-foreignobject-non-zero-xy.html

clip-path/clip-path-geometryBox-2.html

clip-path/clip-path-inline-001.html

clip-path/clip-path-inline-002.html

clip-path/clip-path-inline-003.html

clip-path/clip-path-inline-004.html

clip-path/clip-path-inline-005.html

clip-path/clip-path-inline-006.html

clip-path/clip-path-inline-007.html

clip-path/clip-path-inline-008.html

clip-path/clip-path-inline-009.html

clip-path/clip-path-inline-010.html

clip-path/clip-path-inset-round-percent.html

clip-path/clip-path-localRef-1.html

clip-path/clip-path-marginBox-1a.html

clip-path/clip-path-marginBox-1b.html

clip-path/clip-path-marginBox-1c.html

clip-path/clip-path-marginBox-1d.html

clip-path/clip-path-mix-blend-mode-1.html

clip-path/clip-path-paddingBox-1a.html

clip-path/clip-path-paddingBox-1b.html

clip-path/clip-path-paddingBox-1c.html

clip-path/clip-path-paddingBox-1d.html

clip-path/clip-path-paddingBox-1e.html

clip-path/clip-path-path-001.html

clip-path/clip-path-path-002.html

clip-path/clip-path-path-003.html

clip-path/clip-path-path-with-zoom-hittest.html

clip-path/clip-path-path-with-zoom.html

clip-path/clip-path-rect-001.html

clip-path/clip-path-rect-002.html

clip-path/clip-path-rect-003.html

clip-path/clip-path-rect-004.html

clip-path/clip-path-reference-box-001.html

clip-path/clip-path-reference-box-002.html

clip-path/clip-path-reference-box-003.html

clip-path/clip-path-reference-box-004.html

clip-path/clip-path-reference-restore.html

clip-path/clip-path-rotated-will-change-transform.html

clip-path/clip-path-round-zero-size.html

clip-path/clip-path-scroll.html

clip-path/clip-path-shape-001.html

clip-path/clip-path-shape-002-units.html

clip-path/clip-path-shape-002.html

clip-path/clip-path-shape-003.html

clip-path/clip-path-shape-004.html

clip-path/clip-path-shape-005.html

clip-path/clip-path-shape-006.html

clip-path/clip-path-shape-007.html

clip-path/clip-path-shape-008.html

clip-path/clip-path-shape-009.html

clip-path/clip-path-shape-010.html

clip-path/clip-path-shape-011.html

clip-path/clip-path-shape-foreignobject-non-zero-xy.html

clip-path/clip-path-shape-hline-vline-keywords.html

clip-path/clip-path-shape-winding.html

clip-path/clip-path-stacking-context-001.html

clip-path/clip-path-strokeBox-1a.html

clip-path/clip-path-strokeBox-1b.html

clip-path/clip-path-strokeBox-1c.html

clip-path/clip-path-svg-text-backdrop-filter.html

clip-path/clip-path-svg-text-font-loading.html

clip-path/clip-path-transform-mutated-001.html

clip-path/clip-path-transform-mutated-002.html

clip-path/clip-path-url-reference-svg-foreignobject-zoomed.html

clip-path/clip-path-viewBox-1a.html

clip-path/clip-path-viewBox-1b.html

clip-path/clip-path-viewBox-1c.html

clip-path/clip-path-viewBox-1d.html

clip-path/clip-path-xywh-001.html

clip-path/clip-path-xywh-002.html

clip-path/clip-path-xywh-003.html

clip-path/interpolation.html

clip-path/reference-local-url-with-base-001.html

clip-path/reference-mutated.html

clip-path/reference-nonexisting-existing-local.html

clip-path/svg-clip-path-circle-offset.html

clip-path/svg-clip-path-ellipse-offset.html

clip-path/svg-clip-path-fixed-values.html

hit-test/clip-path-element-objectboundingbox-001.html

hit-test/clip-path-element-objectboundingbox-002.html

hit-test/clip-path-element-userspaceonuse-001.html

hit-test/clip-path-shape-polygon-and-box-shadow.html

hit-test/clip-path-svg-geometry-box.html

parsing/clip-path-computed.html

parsing/clip-path-invalid.html

parsing/clip-path-shape-parsing.html

parsing/clip-path-valid.html

</wpt>

Specifies a basic shape or references a <a element>clipPath</a> element to create a <a>clipping path</a>.

<pre class=prod><dfn>&lt;clip-source></dfn> = <<url>></pre>

<pre class=prod><dfn>&lt;geometry-box></dfn> = <<shape-box>> | fill-box | stroke-box | view-box</pre>

<div dfn-type="value" dfn-for="clip-path">

: <<basic-shape>>

:: A basic shape function as defined in the CSS Shapes module [[!CSS-SHAPES]]. A basic shape makes use of the specified reference box to size and position the basic shape. If no reference box is specified, the ''mask-clip/border-box'' will be used as reference box.

: <<geometry-box>>

::

If specified in combination with a <<basic-shape>> it provides the reference box for the <<basic-shape>>.

If specified by itself, uses the edges of the specified box, including any corner shaping (e.g. defined by 'border-radius' [[!CSS3BG]]), as clipping path. See also <a href="https://www.w3.org/TR/css-shapes/#shapes-from-box-values">“Shapes from box values”</a> [[!CSS-SHAPES]].

: <dfn>fill-box</dfn>

:: Uses the <a>object bounding box</a> as reference box.

: <dfn>stroke-box</dfn>

:: Uses the <a>stroke bounding box</a> as reference box.

: <dfn>view-box</dfn>

::

Uses the nearest <a href="https://www.w3.org/TR/SVG11/intro.html#TermSVGViewport">SVG viewport</a> as reference box.

If a <a element-attr>viewBox</a> attribute is specified for the <a href="https://www.w3.org/TR/SVG11/intro.html#TermSVGViewport">SVG viewport</a> creating element:

* The reference box is positioned at the origin of the coordinate system established by the <a element-attr>viewBox</a> attribute.

* The dimension of the reference box is set to the <em>width</em> and <em>height</em> values of the <a element-attr>viewBox</a> attribute.

: none

:: No <a>clipping path</a> gets created.

</div>

For SVG elements without associated CSS layout box, the <a>used value</a> for ''mask-clip/content-box'' and ''mask-clip/padding-box'' is ''clip-path/fill-box'' and for ''mask-clip/border-box'' and ''mask-clip/margin-box'' is ''clip-path/stroke-box''.

For elements with associated CSS layout box, the <a>used value</a> for ''clip-path/fill-box'' is ''mask-clip/content-box'' and for ''clip-path/stroke-box'' and ''clip-path/view-box'' is ''mask-clip/border-box''.

A computed value of other than ''clip-path/none'' results in the creation of a <a>stacking context</a> [[!CSS21]] the same way that CSS 'opacity' [[CSS3COLOR]] does for values other than ''1''.

If the URI reference is not valid (e.g it points to an object that doesn't exist or the object is not a <a element>clipPath</a> element), no clipping is applied.

<div class=example>

This example demonstrates the use of the basic shape <<polygon()>> as clipping path. Each space separated length pair represents one point of the polygon. The visualized clipping path can be seen in the <a href="#clipping">introduction</a>.

<pre><code highlight=css>

clip-path: polygon(15px 99px, 30px 87px, 65px 99px, 85px 55px,

122px 57px, 184px 73px, 198px 105px, 199px 150px,

145px 159px, 155px 139px, 126px 120px, 112px 138px,

80px 128px, 39px 126px, 24px 104px);

</code></pre>

</div>

<div class=example>

In this example, the 'clip-path' property references an SVG <a element>clipPath</a> element. Each comma separated length pair represents one point of the polygon. As for the previous example, the visualized clipping path can be seen in the <a href="#clipping">introduction</a>.

<pre><code highlight=css>

clip-path: url("#clip1");

</code></pre>

<pre><code highlight=xml>

&lt;clipPath id="clip1">

&lt;polygon points="15,99 30,87 65,99 85,55 122,57 184,73 198,105

199,150 145,159 155,139 126,120 112,138 80,128 39,126 24,104"/>

&lt;/clipPath>

</code></pre>

</div>

The 'clip-path' property is a <a href="https://www.w3.org/TR/2011/REC-SVG11-20110816/intro.html#TermPresentationAttribute">presentation attribute</a> for SVG elements.

# SVG Clipping Path Sources # {#svg-clipping-paths}

## The <a element>clipPath</a> element ## {#ClipPathElement}

<table class="definition-table">

<tr>

<th>Name:</th>

<td><dfn element>clipPath</dfn>

</tr>

<tr>

<th>Categories:</th>

<td><a>container elements</a>, <a>never-rendered element</a></td>

</tr>

<tr>

<th>Content model:</th>

<td>Any number of the following elements, in any order: <ul class=no-bullets><li><a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/intro.html#TermDescriptiveElement'>descriptive</a> <span class=expanding> — <a element>desc</a>, <a element>title</a>, <a element>metadata</a></span></li><li><a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/intro.html#TermAnimationElement'>animation</a> <span class=expanding> — <a element>animate</a>, <a element>animateMotion</a>, <a element>animateTransform</a>, <a element>set</a></span></li><li><a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/intro.html#TermShapeElement'>shape</a> <span class=expanding> — <a element>circle</a>, <a element>ellipse</a>, <a element>line</a>, <a element>path</a>, <a element>polygon</a>, <a element>polyline</a>, <a element>rect</a></span></li><li><a element>text</a></li><li><a element>use</a></li><li><a element>script</a></li></ul></td>

</tr>

<tr>

<th>Attributes:</th>

<td><ul class=no-bullets><li><a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/intro.html#TermConditionalProcessingAttribute'>conditional processing attributes</a><span class=expanding> — <a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/struct.html#RequiredFeaturesAttribute'><span class=attr-name>‘requiredFeatures’</span></a>, <a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/struct.html#RequiredExtensionsAttribute'><span class=attr-name>‘requiredExtensions’</span></a>, <a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/struct.html#SystemLanguageAttribute'><span class=attr-name>‘systemLanguage’</span></a></span></li><li><a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/intro.html#TermCoreAttributes'>core attributes</a><span class=expanding> — <a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/struct.html#IDAttribute'><span class=attr-name>‘id’</span></a>, <a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/struct.html#XMLBaseAttribute'><span class=attr-name>‘xml:base’</span></a>, <a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/struct.html#XMLLangAttribute'><span class=attr-name>‘xml:lang’</span></a>, <a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/struct.html#XMLSpaceAttribute'><span class=attr-name>‘xml:space’</span></a></span></li><li><a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/intro.html#TermPresentationAttribute'>presentation attributes</a><span class=expanding> — 'alignment-baseline', 'baseline-shift', 'clip', 'clip-path', 'clip-rule', 'color', 'color-interpolation', 'color-interpolation-filters', 'color-profile', 'color-rendering', 'cursor', 'direction', 'display', 'dominant-baseline', 'enable-background', 'fill', 'fill-opacity', 'fill-rule', 'filter', 'flood-color', 'flood-opacity', 'font', 'font-family', 'font-size', 'font-size-adjust', 'font-stretch', 'font-style', 'font-variant', 'font-weight', 'glyph-orientation-horizontal', 'glyph-orientation-vertical', 'image-rendering', 'kerning', 'letter-spacing', 'lighting-color', 'marker', 'marker-end', 'marker-mid', 'marker-start', 'mask', 'opacity', 'overflow', 'pointer-events', 'shape-rendering', 'stop-color', 'stop-opacity', 'stroke', 'stroke-dasharray', 'stroke-dashoffset', 'stroke-linecap', 'stroke-linejoin', 'stroke-miterlimit', 'stroke-opacity', 'stroke-width', 'text-anchor', 'text-decoration', 'text-rendering', 'unicode-bidi', 'visibility', 'word-spacing', 'writing-mode'</span></li><li><a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/styling.html#ClassAttribute'><span class=attr-name>‘class’</span></a></li><li><a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/styling.html#StyleAttribute'><span class=attr-name>‘style’</span></a></li><li><a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/struct.html#ExternalResourcesRequiredAttribute'><span class=attr-name>‘externalResourcesRequired’</span></a></li><li><a href='https://www.w3.org/TR/2011/REC-SVG11-20110816/coords.html#TransformAttribute'><span class=attr-name>‘transform’</span></a></li><li>‘<a element-attr for=clipPath>clipPathUnits</a>’</li></ul></td>

</tr>

<tr>

<th>DOM Interfaces:</th>

<td><a class=idlinterface href='#InterfaceSVGClipPathElement'>SVGClipPathElement</a></td>

</tr>

</table>

<wpt>

clip-path/clip-path-scaled-video.html

clip-path/clip-path-svg-text-css.html

clip-path-svg-content/clip-path-clip-nested-twice.svg

clip-path-svg-content/clip-path-clip-rule-001.svg

clip-path-svg-content/clip-path-clip-rule-002.svg

clip-path-svg-content/clip-path-clip-rule-003.svg

clip-path-svg-content/clip-path-clip-rule-004.svg

clip-path-svg-content/clip-path-clip-rule-005.svg

clip-path-svg-content/clip-path-clip-rule-006.svg

clip-path-svg-content/clip-path-clip-rule-007.svg

clip-path-svg-content/clip-path-clip-rule-008.svg

clip-path-svg-content/clip-path-clip-rule-009.svg

clip-path-svg-content/clip-path-clip-rule-010.svg

clip-path-svg-content/clip-path-clip.svg

clip-path-svg-content/clip-path-content-clip-001.svg

clip-path-svg-content/clip-path-content-clip-002.svg

clip-path-svg-content/clip-path-content-clip-003.svg

clip-path-svg-content/clip-path-content-clip-004.svg

clip-path-svg-content/clip-path-content-invisible.svg

clip-path-svg-content/clip-path-content-syling.svg

clip-path-svg-content/clip-path-content-use-001.svg

clip-path-svg-content/clip-path-content-use-002.svg

clip-path-svg-content/clip-path-content-use-003.svg

clip-path-svg-content/clip-path-content-use-004.svg

clip-path-svg-content/clip-path-content-use-005.svg

clip-path-svg-content/clip-path-content-use-006.svg

clip-path-svg-content/clip-path-content-use-007.svg

clip-path-svg-content/clip-path-css-transform-001.svg

clip-path-svg-content/clip-path-css-transform-002.svg

clip-path-svg-content/clip-path-css-transform-003.svg

clip-path-svg-content/clip-path-css-transform-004.svg

clip-path-svg-content/clip-path-dom-child-changes.svg

clip-path-svg-content/clip-path-dom-clippathunits.svg

clip-path-svg-content/clip-path-dom-href.svg

clip-path-svg-content/clip-path-dom-id.svg

clip-path-svg-content/clip-path-inset-stroke-001.svg

clip-path-svg-content/clip-path-inset-stroke-002.svg

clip-path-svg-content/clip-path-invalid-reference.svg

clip-path-svg-content/clip-path-invalid.svg

clip-path-svg-content/clip-path-negative-scale.svg

clip-path-svg-content/clip-path-no-content-001.svg

clip-path-svg-content/clip-path-no-content-002.svg

clip-path-svg-content/clip-path-no-content-003.svg

clip-path-svg-content/clip-path-no-content-004.svg

clip-path-svg-content/clip-path-no-content-005.svg

clip-path-svg-content/clip-path-objectboundingbox-001.svg

clip-path-svg-content/clip-path-objectboundingbox-002.svg

clip-path-svg-content/clip-path-objectboundingbox-003.svg

clip-path-svg-content/clip-path-objectboundingbox-004.svg

clip-path-svg-content/clip-path-on-g-001.svg

clip-path-svg-content/clip-path-on-g-002.svg

clip-path-svg-content/clip-path-on-g-003.svg

clip-path-svg-content/clip-path-on-g-004.svg

clip-path-svg-content/clip-path-on-g-005.svg

clip-path-svg-content/clip-path-on-marker-001.svg

clip-path-svg-content/clip-path-on-marker-002.svg

clip-path-svg-content/clip-path-on-marker-003.svg

clip-path-svg-content/clip-path-on-svg-001.svg

clip-path-svg-content/clip-path-on-svg-002.svg

clip-path-svg-content/clip-path-on-svg-003.svg

clip-path-svg-content/clip-path-on-svg-004.svg

clip-path-svg-content/clip-path-on-svg-005.svg

clip-path-svg-content/clip-path-on-use-001.svg

clip-path-svg-content/clip-path-on-use-002.svg

clip-path-svg-content/clip-path-precision-001.svg

clip-path-svg-content/clip-path-recursion-001.svg

clip-path-svg-content/clip-path-recursion-002.svg

clip-path-svg-content/clip-path-shape-circle-001.svg

clip-path-svg-content/clip-path-shape-circle-002.svg

clip-path-svg-content/clip-path-shape-circle-003.svg

clip-path-svg-content/clip-path-shape-circle-004.svg

clip-path-svg-content/clip-path-shape-circle-005.svg

clip-path-svg-content/clip-path-shape-ellipse-001.svg

clip-path-svg-content/clip-path-shape-ellipse-002.svg

clip-path-svg-content/clip-path-shape-inset-001.svg

clip-path-svg-content/clip-path-shape-inset-002.svg

clip-path-svg-content/clip-path-shape-polygon-001.svg

clip-path-svg-content/clip-path-shape-polygon-002.svg

clip-path-svg-content/clip-path-shape-polygon-003.svg

clip-path-svg-content/clip-path-text-001.svg

clip-path-svg-content/clip-path-text-002.svg

clip-path-svg-content/clip-path-text-003.svg

clip-path-svg-content/clip-path-text-004.svg

clip-path-svg-content/clip-path-text-005.svg

clip-path-svg-content/clip-path-userspaceonuse-001.svg

clip-path-svg-content/clip-path-with-opacity.svg

clip-path-svg-content/clip-path-with-transform.svg

clip-path-svg-content/mask-and-nested-clip-path.svg

clip-path-svg-content/mask-nested-clip-path-001.svg

clip-path-svg-content/mask-nested-clip-path-002.svg

clip-path-svg-content/mask-nested-clip-path-003.svg

clip-path-svg-content/mask-nested-clip-path-004.svg

clip-path-svg-content/mask-nested-clip-path-005.svg

clip-path-svg-content/mask-nested-clip-path-006.svg

clip-path-svg-content/mask-nested-clip-path-007.svg

clip-path-svg-content/mask-nested-clip-path-008.svg

clip-path-svg-content/mask-nested-clip-path-009.svg

clip-path-svg-content/mask-nested-clip-path-010.svg

clip-path-svg-content/mask-nested-clip-path-panning-001.svg

clip-path-svg-content/mask-nested-clip-path-panning-002.svg

clip-path-svg-content/mask-objectboundingbox-content-clip-transform.svg

clip-path-svg-content/mask-objectboundingbox-content-clip.svg

clip-path-svg-content/mask-userspaceonuse-content-clip-transform.svg

clip-path-svg-content/mask-userspaceonuse-content-clip.svg

</wpt>

<em>Attribute definitions:</em>

<dl dfn-type=element-attr dfn-for=clipPath>

: <dfn element-attr>clipPathUnits</dfn> = "''clipPathUnits/userSpaceOnUse'' | ''clipPathUnits/objectBoundingBox''"

::

Defines the coordinate system for the contents of the <a element>clipPath</a>.

: <dfn dfn-type=value dfn-for=clipPathUnits>userSpaceOnUse</dfn>

:: The contents of the <a element>clipPath</a> represent values in the current <a>user coordinate system</a> in place at the time when the <a element>clipPath</a> element is referenced (i.e., the <a>user coordinate system</a> for the element referencing the <a element>clipPath</a> element via the 'clip-path' property).

: <dfn dfn-type=value dfn-for=clipPathUnits>objectBoundingBox</dfn>

:: The coordinate system has its origin at the top left corner of the <a>bounding box</a> of the element to which the clipping path applies to and the same width and height of this <a>bounding box</a>. <a href="https://www.w3.org/TR/SVG/coords.html#Units">User coordinates</a> are sized equivalently to the CSS ''px'' unit.

If attribute <a element-attr>clipPathUnits</a> is not specified, then the effect is as if a value of ''clipPathUnits/userSpaceOnUse'' were specified.

Animatable: yes.

</dl>

CSS properties inherit into the <a element>clipPath</a> element from its ancestors; properties do <em>not</em> inherit from the element referencing the <a element>clipPath</a> element.

<a element>clipPath</a> elements are never rendered directly; their only usage is as something that can be referenced using the 'clip-path' property. The 'display' property does not apply to the <a element>clipPath</a> element; thus, <a element>clipPath</a> elements are not directly rendered even if the 'display' property is set to a value other than ''display/none'', and <a element>clipPath</a> elements are available for referencing even when the 'display' property on the <a element>clipPath</a> element or any of its ancestors is set to ''display/none''.

A <a element>clipPath</a> element can contain <a element>path</a> elements, <a element>text</a> elements, <a>basic shapes</a> (such as <a element>circle</a>) or a <a element>use</a> element. If a <a element>use</a> element is a child of a <a element>clipPath</a> element, it must directly reference <a element>path</a>, <a element>text</a> or <a>basic shapes</a> elements. Indirect references are an error and the <a element>clipPath</a> element must be ignored.

Issue(17): Firefox disables rendering of elements referencing clipPaths with violated content model. No browser ignores clipPath on use with indirect reference.

The raw geometry of each child element exclusive of rendering properties such as 'fill', 'stroke', 'stroke-width' within a <a element>clipPath</a> conceptually defines a 1-bit mask (with the possible exception of anti-aliasing along the edge of the geometry) which represents the silhouette of the graphics associated with that element. Anything outside the outline of the object is masked out. If a child element is made invisible by 'display' or 'visibility' it does not contribute to the clipping path. When the <a element>clipPath</a> element contains multiple child elements, the silhouettes of the child elements are logically OR'd together to create a single silhouette which is then used to restrict the region onto which paint can be applied. Thus, a point is inside the clipping path if it is inside any of the children of the <a element>clipPath</a>.

Issue(170): Define raw geometry with regards to CSS properties that affect it. Especially on text.

For a given <a>graphics element</a>, the actual clipping path used will be the intersection of the clipping path specified by its 'clip-path' property (if any) with any clipping paths on its ancestors, as specified by the 'clip-path' property on the elements which establish a new viewport. (See [[!SVG11]])

A couple of additions:

* The <a element>clipPath</a> element itself and its child elements do <em>not</em> inherit clipping paths from the ancestors of the <a element>clipPath</a> element.

* The <a element>clipPath</a> element or any of its children can specify property 'clip-path'.<br> If a valid 'clip-path' reference is placed on a <a element>clipPath</a> element, the resulting clipping path is the intersection of the contents of the <a element>clipPath</a> element with the referenced clipping path.<br> If a valid 'clip-path' reference is placed on one of the children of a <a element>clipPath</a> element, then the given child element is clipped by the referenced clipping path before OR'ing the silhouette of the child element with the silhouettes of the other child elements.

* An empty clipping path will completely clip away the element that had the 'clip-path' property applied.

## Winding Rules: the 'clip-rule' property ## {#the-clip-rule}

<pre class=propdef>

Name: clip-rule

Value: nonzero | evenodd

Initial: nonzero

Applies to: Applies to SVG <a>graphics elements</a>

Inherited: yes

Percentages: n/a

Computed value: as specified

Media: visual

Animation type: discrete

</pre>

<wpt>

clip-rule/clip-rule-no-interpolation.html

parsing/clip-rule-computed.html

parsing/clip-rule-invalid.html

parsing/clip-rule-valid.html

</wpt>

The 'clip-rule' property indicates the algorithm which is to be used to determine whether a given point is inside a shape for a <a>clipping region</a> created with a <a>graphics element</a>. The definition of the algorithms and the 'clip-rule' values follows the definition of the 'fill-rule' property. See section <a href="https://www.w3.org/TR/2011/REC-SVG11-20110816/painting.html#FillProperties">“Fill Properties”</a> in SVG 1.1 [[!SVG11]].

<dl dfn-type=value dfn-for=clip-rule>

: <dfn>nonzero</dfn>

:: See description of 'fill-rule' property [[!SVG11]].

: <dfn>evenodd</dfn>

:: See description of 'fill-rule' property [[!SVG11]].

</dl>

The 'clip-rule' property only applies to <a>graphics elements</a> that are contained within a <a element>clipPath</a> element.

Note: The 'clip-rule' property does not apply to <<basic-shape>>s.

<div class=example>

<p>The following drawing illustrates the <a value>nonzero</a> rule:

<div class=figure>

<p><img src="images/cliprule-nonzero.svg" alt="Shape with nonzero rule." width="450" style="border: solid black 1px;">

<p class=caption>Three shapes from left to right: Star with 5 points drawn in one continuous, overlapping line; 2 clockwise drawn circles, one contains the other and both are subpaths of the same shape; 2 circles, one containing the other with the bigger one drawn in a clockwise direction and the smaller one in a counter-clockwise direction and both belonging to the same shape. Only the last shape has a "hole".

</div>

<p>The following drawing illustrates the <a value>evenodd</a> rule:

<div class=figure>

<p><img src="images/cliprule-evenodd.svg" alt="Shape with even-odd rule." width="450" style="border: solid black 1px;">

<p class=caption>Three shapes from left to right: Star with 5 points drawn in one continuous, overlapping line; 2 clockwise drawn circles, one contains the other and both are subpaths of the same shape; 2 circles, one containing the other with the bigger one drawn in a clockwise direction and the smaller one in a counter-clockwise direction and both belonging to the same shape. All 3 shapes have a "hole".

</div>

</div>

<div class=example>

The following fragment of code will cause an even-odd clipping rule to be applied to the clipping path because 'clip-rule' is specified on the <a element>path</a> element that defines the clipping shape:

<pre><code highlight=svg>

&lt;g clip-rule="nonzero"&gt;

&lt;clipPath id="MyClip"&gt;

&lt;path d="..." clip-rule="evenodd" /&gt;

&lt;/clipPath&gt;

&lt;rect clip-path="url(#MyClip)" ... /&gt;

&lt;/g&gt;

</code></pre>

whereas the following fragment of code will <em>not</em> cause an evenodd clipping rule to be applied because the 'clip-rule' is specified on the referencing element, not on the object defining the clipping shape:

<pre><code highlight=svg>

&lt;g clip-rule="nonzero"&gt;

&lt;clipPath id="MyClip"&gt;

&lt;path d="..." /&gt;

&lt;/clipPath&gt;

&lt;rect clip-path="url(#MyClip)" clip-rule="evenodd" ... /&gt;

&lt;/g&gt;

</code></pre>

</div>

The 'clip-rule' property is a <a href="https://www.w3.org/TR/2011/REC-SVG11-20110816/intro.html#TermPresentationAttribute">presentation attribute</a> for SVG elements.

# Positioned Masks # {#positioned-masks}

## Mask Image Source: the 'mask-image' property ## {#the-mask-image}

<pre class=propdef>

Name: mask-image

Value: <<mask-reference>>#

Initial: none

Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a element>defs</a> element, all <a>graphics elements</a> and the <a element>use</a> element

Inherited: no

Percentages: n/a

Computed value: list, each item the keyword ''mask-image/none'', a computed <<image>>, or a computed <<url>>

Media: visual

Animation type: discrete

</pre>

<wpt>

animations/mask-image-interpolation.html

mask-image/firefox-bug-1928736-crash.html

mask-image/mask-image-1a.html

mask-image/mask-image-1b.html

mask-image/mask-image-1c.html

mask-image/mask-image-1d.html

mask-image/mask-image-2.html

mask-image/mask-image-3a.html

mask-image/mask-image-3b.html

mask-image/mask-image-3c.html

mask-image/mask-image-3d.html

mask-image/mask-image-3e.html

mask-image/mask-image-3f.html

mask-image/mask-image-3g.html

mask-image/mask-image-3h.html

mask-image/mask-image-3i.html

mask-image/mask-image-4a.html

mask-image/mask-image-4b.html

mask-image/mask-image-5.html

mask-image/mask-image-6.html

mask-image/mask-image-cors-001.sub.html

mask-image/mask-image-inline-sliced-1.html

mask-image/mask-image-svg-foreignobject-zoomed.html

mask-image/mask-image-svg-gradient-zoomed.html

mask-image/mask-image-svg-viewport-changed.html

mask-image/mask-opacity-1a.html

mask-image/mask-opacity-1b.html

mask-image/mask-opacity-1c.html

mask-image/mask-opacity-1d.html

mask-image/mask-opacity-1e.html

mask-image/mask-under-border-radius.html

</wpt>

This property sets the <dfn export>mask layer image</dfn> of an element. Where:

<pre class=prod><dfn>&lt;mask-reference></dfn> = none | <<image>> | <<mask-source>></pre>

<pre class=prod><dfn>&lt;mask-source></dfn> = <<url>></pre>

<dl dfn-type=value dfn-for="mask-image">

: <dfn>&lt;url></dfn>

:: A URL reference to a <a element>mask</a> element (for example ''url(commonmasks.svg#mask)'') or to a CSS image.

: none

:: A value of ''mask-image/none'' counts as a transparent black image layer.

</dl>

<wpt>

mask-image/mask-image-data-url-image.html

mask-image/mask-image-ib-split-2.html

mask-image/mask-image-ib-split.html

mask-image/mask-image-svg-child-will-change.html

mask-image/mask-image-url-image-hash.html

mask-image/mask-image-url-image.html

mask-image/mask-image-url-local-mask.html

mask-image/mask-image-url-remote-mask.html

</wpt>

A computed value of other than ''mask-image/none'' results in the creation of a <a>stacking context</a> [[!CSS21]] the same way that CSS 'opacity' [[CSS3COLOR]] does for values other than ''1''.

A mask reference that is an empty image (zero width or zero height), that fails to download, is not a reference to an <a element>mask</a> element, is non-existent, or that cannot be displayed (e.g. because it is not in a supported image format) still counts as an image layer of transparent black.

See the section <a href="#MaskValues">“Mask processing”</a> for how to process a <a>mask layer image</a>.

Note: A value of ''mask-image/none'' in a list of <<mask-reference>>s may influence the masking operation depending on the used compositing operator specified by 'mask-composite'.

Note: A <<mask-source>> counts as mask layer and can be combined in a repeatable <<mask-reference>> list with <<image>> or further <<mask-source>> list items.

Note: An element can also be masked with 'mask-border-source'. See 'mask-border-source' for the interaction of that property with 'mask-image'.

<div class="example">

Examples for mask references:

<pre><code highlight=css>

body { mask-image: linear-gradient(black 0%, transparent 100%) }

p { mask-image: none }

div { mask-image: url(resources.svg#mask2) }

</code></pre>

</div>

See the section <a href="#layering">“Layering multiple mask layer images”</a> for how 'mask-image' interacts with other comma-separated mask properties to form each mask layer.

## Mask Image Interpretation: the 'mask-mode' property ## {#the-mask-mode}

<pre class=propdef>

Name: mask-mode

Value: <<masking-mode>>#

Initial: match-source

Applies to: All elements. In SVG, it applies to <a>container elements</a> excluding the <a element>defs</a> element, all <a>graphics elements</a> and the <a element>use</a> element

Inherited: no

Percentages: n/a

Computed value: list, each item the keyword as specified

Media: visual

Animation type: discrete

</pre>

<wpt>

mask-image/mask-mode-a.html

mask-image/mask-mode-b.html

mask-image/mask-mode-c.html

mask-image/mask-mode-d.html

mask-image/mask-mode-e.html

mask-image/mask-mode-luminance-with-mask-size.html

mask-image/mask-mode-to-mask-type-svg.html

mask-image/mask-mode-to-mask-type.html

</wpt>

The 'mask-mode' property indicates whether the <<mask-reference>> is treated as luminance mask or alpha mask. (See <a href="#MaskValues">Mask processing</a>.)

<pre class=prod><dfn>&lt;masking-mode></dfn> = alpha | luminance | match-source</pre>

Values have the following meanings:

<dl dfn-type=value dfn-for="mask-mode">

: <dfn>alpha</dfn>

:: A value of ''mask-mode/alpha'' indicates that the alpha values of the <a>mask layer image</a> should be used as the mask values. See <a href="#MaskValues">Calculating mask values</a>.

: <dfn>luminance</dfn>

:: A value of ''mask-mode/luminance'' indicates that the luminance values of the <a>mask layer image</a> should be used as the mask values. See <a href="#MaskValues">Calculating mask values</a>.

: <dfn>match-source</dfn>

::

If the <<mask-reference>> of the 'mask-image' property is of type <<mask-source>> the value specified by the referenced <a element>mask</a> element's 'mask-type' property must be used.

If the <<mask-reference>> of the 'mask-image' property is of type <<image>> the alpha values of the <a>mask layer image</a> should be used as the mask values.

</dl>

<div class="example">

In the following example, the 'mask-type' property sets the mask type value for the <a element>mask</a> element to ''mask-type/alpha''. The 'mask-image' property has a reference to this <a element>mask</a> element and the 'mask-mode' property has a value of ''mask-mode/luminance''. The 'mask-mode' property will override the definition of 'mask-type' to ''mask-type/luminance''.

The 'mask-mode' property must not affect the masking mode of 'mask-border-source'.

<pre><code highlight=svg>

&lt;mask id="SVGMask" mask-type="alpha" maskContentUnits="objectBoundingBox"&gt;

&lt;radialGradient id="radialFill"&gt;

&lt;stop stop-color="white" offset="0"/&gt;

&lt;stop stop-color="black" offset="1"/&gt;

&lt;/radialGradient&gt;

&lt;circle fill="url(#radialFill)" cx="0.5" cy="0.5" r="0.5"/&gt;

&lt;/mask&gt;

&lt;style&gt;

rect {

mask-image: url(#SVGMask);

mask-mode: luminance;

}

&lt;/style&gt;

&lt;rect width="200" height="200" fill="green"/&gt;