Skip to content
LibraryCSS
Türkçe
maskAdvancedUsed in 54 effects

Alpha masking with CSS mask

A CSS mask uses another image as a visibility map. Opaque mask pixels reveal the element, transparent pixels hide it, and partial alpha produces a soft fade. The mask itself is never painted; only its alpha or luminance changes the element's final visibility.

This is the key difference from clip-path: clipping defines a hard inside/outside boundary, while masking can express gradual opacity, texture, and multiple composited layers.

Think in alpha, not visible mask color

With the common alpha mode, black and white are both fully opaque and therefore both reveal the element. Transparency is what hides it. Write gradients from opaque color to transparent, not from black to white, when you need a fade.

The element's own background, image, and content supply the visible color. This makes one SVG mask reusable with any background-color.

mask-image
Supplies one or more gradient, raster, or SVG mask layers.
mask-size
Sizes mask layers independently from the element's painted background.
mask-repeat
Controls tiling; icon masks commonly use no-repeat.
cssFade the top and bottom edges
.scroll-region {
  -webkit-mask-image: linear-gradient(
    to bottom, transparent, #000 3rem,
    #000 calc(100% - 3rem), transparent
  );
  mask-image: linear-gradient(
    to bottom, transparent, #000 3rem,
    #000 calc(100% - 3rem), transparent
  );
}

Build recolorable icons

Use an SVG silhouette as the mask and paint the icon with background: currentColor. The same asset then follows text color, hover states, and themes without editing the SVG file.

Set size, position, and repetition explicitly. An omitted mask-repeat: no-repeat can tile a small icon across the entire box.

cssA theme-aware masked icon
.icon {
  width: 1.25rem;
  aspect-ratio: 1;
  background: currentColor;
  -webkit-mask: url("star.svg") center / contain no-repeat;
  mask: url("star.svg") center / contain no-repeat;
}

Combine layers for real cutouts

Multiple mask layers can be combined to subtract a center from an outer shape, producing a genuinely transparent ring. mask-composite describes how the current layer combines with the layers beneath it.

WebKit's prefixed composite keywords differ from the standard vocabulary in some deployed browsers. Keep the prefixed and unprefixed recipes together and test the exact target set.

Separate visual transparency from interaction

A masked-away pixel is visually absent, but complex hit testing can still surprise across browser versions and nested elements. Do not place unrelated controls underneath a large masked box without testing pointer behavior.

Mask image values generally do not interpolate as useful strings. Animate position, size, transform, or a typed custom property used inside a gradient instead.

Live catalog examples

These production examples use mask. Open any effect to inspect its complete source and experiment in the browser editor.

View all 54 effects using mask

Browser support

Support notes refer to stable, unprefixed behavior unless a prefix is explicitly listed.

FeatureBrowsersNote
mask / mask-imageAll current major browsersPrefixed declarations remain useful for Safari compatibility.
mask-compositeModern browsers with syntax differencesTest standard and WebKit composite keywords separately.
Gradient masksAll current major browsersAlpha gradients are the most portable soft-mask source.

Common pitfalls

  • The gradient runs from black to white

    Both colors are opaque in alpha mode. Fade to transparent instead.

  • WebKit declarations are omitted

    Keep prefixed mask declarations when Safari versions in your support range require them.

  • Composite keywords are copied across syntaxes

    Standard and prefixed implementations can use different keyword models.

  • The whole mask image is transitioned

    Animate geometry or a typed value used by the mask rather than the image string.

Frequently asked questions

How is mask different from clip-path?
A mask supports partial alpha and soft edges; clip-path defines a hard geometric boundary.
Why does black still reveal the element?
The default behavior usually reads alpha. Opaque black and opaque white both have full alpha.
Can I recolor an SVG with a mask?
Yes. Use the SVG as the mask and set the visible color with the element's background.
Can masks be animated?
Position, size, transforms, and numeric gradient inputs animate more reliably than complete mask-image strings.

Related guides

Last updated:

All guides