CSS mask-mode Property

What You’ll Learn

The mask-mode property controls how a mask-image is interpreted — using its alpha channel, its luminance values, or matching the source automatically.

Introduction

The mask-mode property in CSS defines how the mask image is applied to an element. Masks can hide or reveal portions of an element, and mask-mode determines whether the alpha channel or the luminance channel of the mask image controls visibility.

This property is particularly useful for creating complex visual effects by selectively displaying or hiding parts of an element based on the mask. Pair it with mask-image to choose the mask source first, then use mask-mode to decide how that source is read.

Definition and Usage

Use mask-mode: alpha when your mask PNG or SVG has meaningful transparency. Use mask-mode: luminance when you want lighter pixels to stay visible and darker pixels to hide content — common with grayscale photos or illustrations. Leave it at the default match-source when you want the browser to pick the best interpretation automatically.

📝 Syntax

The syntax for the mask-mode property uses one of three keyword values:

element {
  mask-mode: mode;
}

Here, mode can be one of the specified keywords: match-source, alpha, or luminance.

Basic Example

.mask-alpha {
  width: 300px;
  height: 200px;
  background: url('/images/valley-pattern.jpg') center/cover;
  -webkit-mask-image: url('/images/apple.png');
  mask-image: url('/images/apple.png');
  -webkit-mask-size: contain;
  mask-size: contain;
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-mode: alpha;
  mask-mode: alpha;
}

.mask-luminance {
  width: 300px;
  height: 200px;
  background: url('/images/valley-pattern.jpg') center/cover;
  -webkit-mask-image: url('/images/orange.png');
  mask-image: url('/images/orange.png');
  -webkit-mask-size: contain;
  mask-size: contain;
  -webkit-mask-repeat: no-repeat;
  mask-repeat: no-repeat;
  -webkit-mask-mode: luminance;
  mask-mode: luminance;
}

Syntax Rules

• The initial value is match-source.
• mask-mode only applies when a mask-image is set.
• alpha reads transparency from the mask image’s alpha channel.
• luminance uses brightness — lighter areas stay visible, darker areas are hidden.
• Include -webkit-mask-mode alongside mask-mode for broader Safari support.

💎 Property Values

The mask-mode property accepts three keyword values that control how the mask image is read.

🎯 Default Value

The default value of the mask-mode property is match-source, which means the mask mode will match the source image type. If the mask image has an alpha channel, alpha is used; otherwise the browser falls back to luminance.

Alpha vs Luminance

Examples Gallery

Compare alpha and luminance mask modes side by side, then explore each mode individually and the default match-source behavior.

<style>
  .mask-alpha {
    width: 280px;
    height: 200px;
    background: url('/images/valley-pattern.jpg') center/cover;
    -webkit-mask-image: url('/images/apple.png');
    mask-image: url('/images/apple.png');
    -webkit-mask-size: contain;
    mask-size: contain;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-mode: alpha;
    mask-mode: alpha;
  }
  .mask-luminance {
    width: 280px;
    height: 200px;
    background: url('/images/valley-pattern.jpg') center/cover;
    -webkit-mask-image: url('/images/orange.png');
    mask-image: url('/images/orange.png');
    -webkit-mask-size: contain;
    mask-size: contain;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-mode: luminance;
    mask-mode: luminance;
  }
</style>

<div class="mask-alpha"></div>
<div class="mask-luminance"></div>

<style>
  .mask-alpha {
    width: 280px;
    height: 200px;
    background: url('/images/valley-pattern.jpg') center/cover;
    -webkit-mask-image: url('/images/apple.png');
    mask-image: url('/images/apple.png');
    -webkit-mask-size: contain;
    mask-size: contain;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-mode: alpha;
    mask-mode: alpha;
  }
</style>

<div class="mask-alpha"></div>

<style>
  .mask-luminance {
    width: 280px;
    height: 200px;
    background: url('/images/valley-pattern.jpg') center/cover;
    -webkit-mask-image: url('/images/orange.png');
    mask-image: url('/images/orange.png');
    -webkit-mask-size: contain;
    mask-size: contain;
    -webkit-mask-repeat: no-repeat;
    mask-repeat: no-repeat;
    -webkit-mask-mode: luminance;
    mask-mode: luminance;
  }
</style>

<div class="mask-luminance"></div>

/* Default — no mask-mode needed */
.mask-default {
  background: url('/images/valley-pattern.jpg') center/cover;
  -webkit-mask-image: url('/images/apple.png');
  mask-image: url('/images/apple.png');
  -webkit-mask-size: contain;
  mask-size: contain;
  /* mask-mode: match-source; — implicit default */
}

♿ Accessibility

• Set mask-image first — mask-mode has no effect without an active mask layer.
• Do not hide essential content — Masked-away text or controls may be invisible but still exist in the DOM.
• Test both modes — If a mask looks wrong, try switching between alpha and luminance.
• Check contrast — Partially masked areas can reduce readability if text sits over them.
• Offer fallbacks — Ensure content remains usable when masking is unsupported.

Alpha vs Luminance

💡 Best Practices