SVG clipping and masking: when to use each technique

Use a clip path for a hard boundary

A clipPath uses geometry as a stencil. Areas inside the clipping shapes remain visible and areas outside disappear. Fill color usually does not matter because the shapes contribute geometry, not painted appearance.

<defs>
  <clipPath id="avatar-crop">
    <circle cx="80" cy="80" r="64" />
  </clipPath>
</defs>
<image href="portrait.jpg" width="160" height="160"
       clip-path="url(#avatar-crop)" />

Clip paths are ideal for avatar crops, cut-out panels, and revealing artwork inside a logo silhouette. Strokes on clipping geometry can be confusing because clipping is based primarily on the filled region. Convert an outline into a filled shape when stroke width must define the boundary.

Use a mask for soft visibility

A mask can create fades, holes, feathered edges, and texture-based transparency. In the default luminance mode, white reveals, black hides, and gray creates partial visibility. In alpha mode, the source alpha controls visibility and its RGB color does not.

<defs>
  <linearGradient id="fade" x1="0" x2="1">
    <stop offset="0" stop-color="white" />
    <stop offset="1" stop-color="black" />
  </linearGradient>
  <mask id="fade-out">
    <rect width="100%" height="100%" fill="url(#fade)" />
  </mask>
</defs>

Mask behavior may use luminance or alpha depending on mask-type and the rendering context. The SVG mask element defaults to luminance mode, so set mask-type="alpha" explicitly when only source alpha should control visibility. The MDN mask reference documents the mode and region defaults.

Understand the two coordinate questions

A clipPath chooses the coordinate system for its child geometry through clipPathUnits. A mask has two separate choices: maskUnits for its outer region and maskContentUnits for its child content. Object-bounding-box units express values as fractions of the target object's bounds. User-space units use the current SVG coordinates. Mixing these models is a common reason an effect appears tiny, offset, or missing.

Start with userSpaceOnUse while debugging because the coordinates match the visible canvas. Switch to bounding-box units when the same normalized effect should adapt to objects of different sizes. Remember that bounding-box coordinates usually range from 0 to 1, not from 0 to 100. A clipPath uses userSpaceOnUse by default, while a mask's region uses objectBoundingBox by default and its child content uses userSpaceOnUse. The MDN clipPath reference is a quick source for the clipping default.

Mask regions can crop the effect

A mask has a region that may extend beyond the target. Blurs and feathered edges need extra space or they can be cut off. If a soft edge becomes a hard rectangle, inspect x, y, width, and height on the mask before changing the blur.

Filters inside a mask introduce another region with its own bounds. Debug the mask without the filter first, then add the filter and expand both regions deliberately. This stepwise process separates coordinate errors from filter cropping.

Combine and reuse effects carefully

A target can use both clipping and masking. Apply a clip for the main hard boundary and a mask for a local fade only when the composition truly requires both. Deep stacks of groups, filters, clips, and masks are hard to optimize and can render slowly.

Definitions are referenced by ID, so duplicate IDs can silently connect the wrong effect after files are merged. Keep IDs unique and update every url(#id) reference when renaming. External URL references can introduce loading and security concerns; self-contained definitions are more portable.

Clipping and masking checklist

1. Choose a clip for binary visibility and a mask for partial visibility.
2. Confirm every referenced ID is present and unique.
3. Use user-space coordinates for the first working version.
4. Verify the effect region includes feathering, strokes, and filters.
5. Remove nested effects one at a time when debugging.
6. Test against a contrasting temporary background.
7. Check export in the actual browser or application that will display the file.

Inspect the complete source in SVG Vector Lab before and after changing a clip or mask. If a correct effect is still cut off by the canvas, use the viewBox guide to expand the document frame safely.