🎭 Mastering mask-image in CSS

📌 What Is mask-image?

The mask-image property allows you to apply a mask layer to an element. A mask controls which parts of an element are visible and which parts are hidden, based on the alpha (transparency) or luminance (brightness) of the mask image.
This enables advanced cutout effects, custom shapes, gradients, and artistic UI designs. 🎨✨

>>“mask-image lets you hide and reveal elements with creative shapes — like stencils in CSS.”

🧩 Basic Syntax

Syntax

mask-image: url(mask.png);
mask-image: linear-gradient(to bottom, transparent, black);

✔ Multiple masks can be used with commas
✔ Works similar to background-image, but controls visibility instead of pixels.

🎯 How Masks Work (Important!)

  • Black → fully transparent (hidden)
  • White → fully visible
  • Gray → partially visible

Note

In CSS, masks use alpha values by default → The more opaque, the more visible.

🧪 Example: Mask an Image With a Shape

Circle mask

.photo {
  mask-image: url(circle-mask.png);
  mask-size: cover;
  mask-repeat: no-repeat;
}

✔ Only parts of the image inside the circle remain visible.

✨ Using Gradients as Masks

Gradient fade mask

.fade-bottom {
  mask-image: linear-gradient(to bottom, black 70%, transparent);
}

✔ Creates a smooth fade-out effect at the bottom of an element.

🎨 Masking With Multiple Layers

Multiple masks

.shape {
  mask-image: 
    radial-gradient(circle, white 60%, transparent),
    linear-gradient(90deg, white, transparent);
}

✔ Masks stack similarly to multiple backgrounds.

🧠 Additional Mask Properties

  • mask-size — controls scaling (like background-size)
  • mask-position — where to place the mask
  • mask-repeat — repeat or tile the mask
  • mask-mode — alpha or luminance masking
  • mask-origin — border-box / padding-box / content-box
  • mask-composite — how multiple masks combine

🔥 Example: Text Reveal With mask-image

Text masked by gradient

.reveal {
  font-size: 4rem;
  background: url(poster.jpg);
  -webkit-background-clip: text;
  color: transparent;

  mask-image: linear-gradient(to right, transparent, black, transparent);
}

✔ Beautiful “spotlight” text reveal effect.

🎬 Masking SVG Shapes

SVG mask

.logo {
  mask-image: url(logo-mask.svg);
  mask-size: contain;
}

✔ Clean edges and scalable shapes thanks to vector masking.

🌈 Example: Highlight With Mask Movement

Animated mask

@keyframes sweep {
  to { mask-position: 100% 0; }
}

.highlight {
  mask-image: linear-gradient(90deg, transparent, white, transparent);
  mask-size: 200% 100%;
  animation: sweep 2s infinite linear;
}

✔ Creates a shimmering loading or highlighting animation.

🔥 Advanced: mask-image + mix-blend-mode

Combined effect

.shine {
  mask-image: url(mask-shape.png);
  mix-blend-mode: screen;
  opacity: 0.8;
}

✔ Excellent for futuristic UI cards or glowing stickers.

⚠️ Browser Support Notes

  • ✔ Chrome
  • ✔ Safari
  • ✔ Edge
  • ⚠️ Firefox (partial support, uses -webkit-mask-image)

Note

For maximum compatibility, include both mask-image and -webkit-mask-image.

🔍 Debugging Tips

  • If the element disappears → your mask is fully black or fully transparent
  • Try switching gradient direction if mask hides wrong part
  • Use mask-repeat: no-repeat to avoid unexpected tiling
  • Use mask-position to align the mask art correctly

🔗 Helpful Resources

>>“mask-image unlocks next-level visual creativity — your elements become canvases.” 🎭✨