🎭 Mastering mask-mode in CSS

📌 What Is mask-mode?

The mask-mode property controls how the mask image is interpreted — either by its alpha channel (transparency) or by its luminance (brightness).
This determines how much of the masked element is visible.
In simple terms:mask-mode decides whether the mask uses transparency or brightness to reveal content.

>>“mask-mode switches your mask between transparency-based and brightness-based visibility.”

🧩 Basic Syntax

Syntax

mask-mode: alpha | luminance;

✔ Can be applied to one or multiple mask layers
✔ Default value: alpha

🎯 What Each Value Means

ValueHow It WorksBest For
alphaUses mask image transparency:opaque = visible, transparent = hiddenPNGs, SVGs, shapes with transparency
luminanceUses brightness:white = visible, black = hiddenGradients, grayscale masks, soft fades

🧠 Important Difference

alpha cares about transparency.
luminance cares about brightness.

Note

Many mask effects look better with luminance because gradients produce softer fades.

🧪 Example 1 — mask-mode: alpha (Default)

alpha mask

.alpha-mask {
  mask-image: url(star-mask.png); /* PNG with transparent background */
  mask-mode: alpha;
}

✔ Transparency in the PNG decides what is visible.
✔ Perfect for stencil shapes.

🧪 Example 2 — mask-mode: luminance

luminance mask

.light-mask {
  mask-image: url(gradient-mask.jpg); /* grayscale gradient */
  mask-mode: luminance;
}

✔ White areas = fully visible
✔ Black areas = hidden
✔ Great for soft vignette fades and spotlight effects

🧪 Example 3 — Gradient Fade Using Luminance

fade with luminance

.fade {
  mask-image: linear-gradient(to bottom, white, black);
  mask-mode: luminance;
}

✔ Smooth fading reveals based on brightness — ideal for text and images.

🎨 Multiple Masks with Different mask-mode

multiple mask modes

.multi-mask {
  mask-image: url(mask1.png), radial-gradient(circle, white, black);
  mask-mode: alpha, luminance;
}

✔ First mask uses transparency
✔ Second uses brightness
✔ Useful for combining cut-out shapes + soft fades

🔥 Advanced Example — Glow Reveal Effect

glow reveal

.glow {
  mask-image: radial-gradient(circle, white 30%, black 70%);
  mask-mode: luminance;
  mask-size: 150% 150%;
  mask-position: center;
}

✔ Produces a glowing reveal where brightness controls visibility
✔ Works beautifully with animations

🛠️ mask-mode + Animation

animated spotlight

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

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

✔ Creates a sliding spotlight reveal effect using brightness.

🛠️ Best Practices

  • Use alpha for PNG/SVG icons with transparency
  • Use luminance for gradient-based fades
  • Use grayscale images for luminance masks
  • Combine multiple mask layers for complex effects
  • Test across browsers — mask rendering varies slightly

⚠️ Browser Support

  • ✔ Chrome
  • ✔ Safari
  • ✔ Edge
  • ⚠️ Firefox requires -webkit-mask-mode

Note

Always define both mask-mode and -webkit-mask-mode for full compatibility.

🔍 Debugging Tips

  • If mask disappears, ensure the mask image contains transparency or grayscale values
  • If fades aren’t smooth, switch from alpha → luminance
  • Check mask positioning with mask-position
  • If mask is clipped, check mask-clip and mask-origin

🔗 Helpful Resources

>>“mask-mode unlocks two worlds: transparency-based stencils and luminance-driven reveals.” ✨🎭