Clipping & masking

<clipPath> — hard-edged cropping

A <clipPath> works like a stencil cut from paper: the shapes inside the clip path define which region of the target element is visible. Anything inside the clip region is shown at full opacity; anything outside is completely invisible. There is no in-between — the edge is always crisp and hard.

You define the clip region in <defs><clipPath id="…"> and apply it with the clip-path="url(#id)" attribute on any SVG element or group.

Rect clipped to a circle

The simplest example: a filled rectangle is clipped to a circular region. The rectangle's original bounding box is much larger, but only the circular cut-out is visible.

The dashed outline shows the original rectangle boundaries. The teal fill is only visible within the circular clip path. The right-side rectangle has no clip applied — it renders as a normal filled rect. Notice the edge of the clipped shape is perfectly sharp, not feathered at all.

Star clip shape applied to a striped rect

The clip shape can be anything — a polygon, a path, even text. Here a five-pointed star path is used as the clip region. The target element is a rectangle filled with a striped pattern (alternating rect stripes), and the star crop reveals just those stripes within the star silhouette.

Applying clip-path to a <g> group clips the entire group at once, rather than having to apply it to every child element individually. This is particularly useful when the clipped content is complex. Every pixel is still a binary in/out — the stripe edges remain perfectly sharp where they cross the star boundary.

<mask> — soft, value-based visibility

A <mask> is like a clip path that allows partial transparency. Instead of a binary inside/outside rule, SVG masks use the luminance of the mask content to control how much of the masked element shows through:

• White in the mask → the masked element is fully visible (luminance = 1).
• Black in the mask → the masked element is fully hidden (luminance = 0).
• Gray in the mask → the masked element shows through partially (luminance between 0 and 1).

This luminance-based approach means you can use a grayscale gradient inside a mask to produce a smooth fade — something impossible with <clipPath>.

Fade-out with a grayscale gradient mask

The mask contains a linear gradient from white (left) to black (right). Where the mask is white, the teal rectangle is completely visible; where the mask is black, it disappears entirely; the gray middle zone produces the smooth fade.

Note: the gradient inside the mask must be grayscale for correct luminance-based masking. This is a technical requirement of SVG masking, not a palette choice — the result you see is the teal rectangle fading out, which follows the on-palette color rule.

Masking a group with a circular gradient

You can use any shape or combination of shapes inside a <mask>. Here a radial gradient in the mask makes a group of shapes appear to glow from the center and fade toward the edges.

Because the mask's radial gradient is white at the center and black at the edges, the innermost rings are fully visible and the outermost ring fades nearly to nothing. The group as a whole gets a single mask attribute — you do not need to apply the mask to each child circle individually.

Alpha masking

SVG also supports alpha-based masking by setting mask-mode: alpha in CSS (or using maskContentUnits). In alpha mode it is the opacity of the mask content, rather than its luminance, that controls visibility. Luminance masking (the default) is more common in SVG because it works intuitively with CSS color names like white and black — alpha masking requires transparent shapes which are harder to reason about visually.

clipPath vs mask — choosing the right tool

Both features hide parts of an element, but they suit different situations:

• Use clipPath when you need a precise geometric crop with hard edges — cropping an image to a shape, constraining a group to a region, or cutting out a viewport. Clipping is computationally cheap because it is a binary test.
• Use mask when you need soft edges, gradual fades, partial transparency, or any effect where the visibility varies continuously across the element. Masks support gradients, patterns, and any grayscale value range.
• Accessibility note: neither clipping nor masking affects the DOM or ARIA tree — an element that is fully masked is still in the accessibility tree. If you want to hide something from screen readers as well, use display:none or visibility:hidden.
• Performance: clipPath is cheaper than mask. If a hard edge would work, prefer clipPath. Complex masks with large gradients on high-DPI displays can be expensive to composite.

Both figures start with an identical teal rectangle. The left one is clipped to a circle — notice the sharp, aliased-only edge. The right one uses a radial-gradient mask centered on the same area — the teal color fades continuously from the center outward, producing a soft spotlight effect impossible with clipPath alone.