SVG masks and clipping paths: hide parts of a graphic
Use clipPath for hard-edged cut-outs and mask for soft fades. Includes luminance versus alpha, gradient masks, CSS clip-path and mask, and common pitfalls.
Clipping and masking both hide parts of an element without changing its geometry. The difference is the kind of edge you get. A clipping path is a hard cut: a point is either inside the shape or outside. A mask can fade: it can make part of an element half-visible, which is how you build soft edges and gradual fades.
Clipping with clipPath
A <clipPath> element defines a region. MDN describes it as restricting where paint can be applied: parts of the drawing outside the region are not drawn. You reference it with the clip-path property.
Inside a <clipPath> you can put shape elements, <text> and <use>, along with animation and descriptive elements.
<clipPath id="myClip">
<circle cx="40" cy="35" r="35"/>
</clipPath>
<use clip-path="url(#myClip)" href="#heart" fill="red"/>
That is the pattern from MDN’s own example: only the part of the heart inside the circle is visible.
Try it below. Change the circle’s cx, cy or r to move or resize the window. Replace the <circle> with a <rect> or a path to change its shape.
Things to know about clipping
- No partial transparency. A clip path works by region. MDN points to
<mask>for soft or semi-transparent results. - The element’s geometry is unchanged. The bounding box stays what it would be without the clip. Layout and measurements are not affected.
- Pointer events follow the clip. MDN notes that events are not dispatched on clipped regions. A circle of radius 10 clipped to radius 5 will not receive clicks outside the smaller radius.
- Units. The
clipPathUnitsattribute sets the coordinate system for the clip path’s contents. It defaults touserSpaceOnUse, and the other value isobjectBoundingBox.
Soft edges with mask
A <mask> uses the contents of the mask element to decide how visible each part of the masked element is. In the default mode, luminance, brightness decides. MDN lays out the rule:
- White (or any light color): the element is visible.
- Black (or any dark color): the element is hidden.
- Gray: partially visible, in proportion to its brightness.
- Areas of the masked element with no mask content over them are hidden, because the mask’s background is effectively black.
A gradient from white to black is therefore a fade. This is the classic use of masks, and a clip path cannot do it.
The mask applies a white-to-black gradient, so the bar is fully visible on the left and hidden on the right. Swap the two stop-color values to reverse the fade, or add a middle stop to make a band.
Mask details worth knowing
MDN documents these attributes:
| Attribute | Default | Purpose |
|---|---|---|
x, y |
-10% |
Top-left of the masking area |
width, height |
120% |
Size of the masking area |
maskUnits |
objectBoundingBox |
Coordinate system for x, y, width, height |
maskContentUnits |
userSpaceOnUse |
Coordinate system for the mask’s children |
mask-type |
luminance |
Read the mask as luminance or alpha |
The default masking area extends 10 percent beyond the masked element’s bounding box on every side. Outside that area the element is always hidden. If a mask seems to cut off your shape unexpectedly, this is a likely cause. Set maskUnits="userSpaceOnUse" with explicit values, as in the example above, or enlarge the area.
Luminance versus alpha
With mask-type="alpha", only the transparency of the mask content matters. Opaque pixels show the element, and transparent pixels hide it, whatever their color. That is easier to reason about when your mask is a shape rather than a gradient, since you do not need to paint the shape white.
Both modes in action. The first mask paints a black circle over a white background, which punches a hole. The second uses mask-type="alpha" with a single opaque circle, which keeps only that circle.
Choosing between them
Use a clip path when you want a crisp edge or a defined shape. Use a mask when you need a gradient, a feathered edge, or partial opacity. A clip path is simpler to write and to reason about, so start there unless you need softness.
CSS clip-path and mask on HTML
Both ideas work outside SVG too. MDN says the CSS clip-path property applies to all HTML elements. It accepts basic shapes (inset(), circle(), ellipse(), polygon(), path() and others), a geometry box, or a url() pointing at an SVG <clipPath>.
.avatar { clip-path: circle(50%); }
.badge { clip-path: polygon(50% 0, 100% 50%, 50% 100%, 0 50%); }
.cross { clip-path: url("#cross"); } /* an SVG <clipPath> */
Notes from MDN: clipping affects rendering, not layout. Any value other than none creates a stacking context, like opacity below 1. Also, path() uses fixed coordinates and does not grow with the element, whereas shape() can use percentages and scale. MDN labels clip-path as widely available and dates that to January 2020.
For soft effects on HTML, the CSS mask shorthand takes an image, a gradient, or an SVG reference such as url("masks.svg#star"), and mask-mode picks alpha, luminance or match-source. MDN marks the unprefixed mask as widely available since December 2023, and says some parts of the feature may have varying support. For older browsers, MDN lists prefixed -webkit-mask-* properties, so check the compatibility table for your audience before relying on edge features.
.fade-out {
mask-image: linear-gradient(to right, #000, transparent);
}
The SVG <clipPath> and <mask> elements themselves are listed by MDN as widely available since July 2015.
Common problems
- The mask hides everything. Mask content must be light in luminance mode. Black shapes hide, and an empty mask hides the whole element.
- The mask cuts off the edges. Check the default masking area, which is only 120 percent of the bounding box, centered.
- Clicks stop working. Clipped regions do not receive pointer events. Do not clip away an area that has to be clickable.
- Forgetting ids. The reference
url(#id)must match theidexactly, so check spelling and case when a clip or mask seems to do nothing.
When not to use them
If you are masking a photograph for a simple rounded corner, CSS border-radius is clearer. If a mask only simplifies a shape you could draw directly, draw the shape as a path. And if you need blur, glow or color changes rather than hiding, look at filters. To see how the coordinates in these examples map to the screen, read about the viewBox.
Sources
Checked against these references on 2026-11-21.