🎭 Mastering mask-type in CSS (SVG Masking)

📌 What Is mask-type?

The mask-type property is used specifically with SVG masks and determines how the mask is interpreted:
👉 by its luminance (brightness) or
👉 by its alpha (transparency).
It is placed inside an SVG’s <mask> element.
CSS masking uses mask-mode for HTML elements, but SVG uses mask-type.

>>“mask-type tells SVG whether to treat your mask by transparency or by brightness.”

🧩 Basic Syntax

SVG mask-type syntax

<mask id="m1" mask-type="luminance">
  <!-- mask content -->
</mask>

🎯 Values of mask-type

ValueMeaningUse Case
alphaMask uses the alpha channel (opacity)PNG/SVG shapes with transparency
luminanceMask uses brightness (white=visible, black=hidden)Gradients, grayscale masks, soft fades

Note

✔ Default behavior of SVG masks is luminance.
✔ Use alpha when your mask uses transparency instead of brightness.

🧪 Example 1 — Luminance-Based SVG Mask (Default)

Luminance mask

<svg>
  <mask id="fadeMask" mask-type="luminance">
    <rect width="100%" height="100%" fill="url(#fadeGradient)" />
  </mask>

  <linearGradient id="fadeGradient">
    <stop offset="0%" stop-color="white" />
    <stop offset="100%" stop-color="black" />
  </linearGradient>

  <image href="photo.jpg" mask="url(#fadeMask)" />
</svg>

✔ White reveals image
✔ Black hides image
✔ Produces smooth fade-out effect

🧪 Example 2 — Alpha-Based SVG Mask

Alpha mask

<svg>
  <mask id="shapeMask" mask-type="alpha">
    <circle cx="100" cy="100" r="80" fill="black" fill-opacity="1" />
  </mask>

  <image href="pic.png" mask="url(#shapeMask)" />
</svg>

✔ Circle opacity controls reveal
✔ Transparent = hidden
✔ Opaque = visible
✔ Perfect for stencil-like cutout shapes

🎨 mask-type in Action: Cutout Text Effect

Text mask using alpha

<svg>
  <mask id="textMask" mask-type="alpha">
    <text x="0" y="100" font-size="100" fill="white">HELLO</text>
  </mask>

  <rect width="100%" height="100%" fill="blue" mask="url(#textMask)" />
</svg>

✔ Text acts as the mask
✔ Background is shown through the text area
✔ A clean text-cutout effect

🧠 mask-type vs mask-mode

PropertyUsed InPurpose
mask-typeSVG <mask> elementDefines interpretation model (alpha/luminance)
mask-modeCSS masking on HTML elementsDefines how mask is interpreted

✔ They solve the same problem but in different environments.

🔥 Advanced Example — Blurred Spotlight Mask

Spotlight using luminance

<svg>
  <mask id="spotlight" mask-type="luminance">
    <radialGradient id="grad">
      <stop offset="0%" stop-color="white" />
      <stop offset="100%" stop-color="black" />
    </radialGradient>

    <rect fill="url(#grad)" width="100%" height="100%" />
  </mask>

  <image href="stage.jpg" width="100%" mask="url(#spotlight)" />
</svg>

✔ Bright center shows image
✔ Dark edges hide image
✔ Creates a natural spotlight reveal

🛠️ Best Practices

  • Use alpha for SVG masks that rely on opacity
  • Use luminance for grayscale gradient-based masks
  • Avoid unnecessary complexity inside masks — keep shapes simple
  • Use high-resolution mask images for clean edges
  • Remember that mask-type only works in SVG mask elements

⚠️ Browser Support

  • ✔ Chrome
  • ✔ Edge
  • ✔ Safari
  • ✔ Firefox

Note

mask-type is widely supported because it's part of the SVG spec — not CSS masking.

🔍 Debugging Tips

  • If mask looks inverted → try switching alpha ↔ luminance
  • Ensure SVG mask elements are placed before their usage
  • Check that mask shape has proper opacity or brightness
  • Use DevTools “Mask Editing Mode” (Chrome) to preview

🔗 Helpful Resources

>>“mask-type is the key to controlling how SVG masks reveal — by transparency or by light.” ✨