CSS mask-border-mode Property

If this site has been useful, we’d love your support! Consider buying us a coffee to keep things going strong!

Description

The mask-border-mode property controls how the image used as a border mask is interpreted and applied to an element’s border area. In practice it determines the interpretation of the mask image’s pixel data (for example whether alpha channels or luminance are used) and the compositing approach used when that border-specific mask is combined with other masks or with the element’s own painting. Because it targets the border region, it only affects the pixels that result from the border-image / mask-border slicing and tiling operations, not the element’s interior content directly.

The property is used together with the broader border-masking shorthand and related border mask subproperties — for specifying the mask source, slice, repeat and widths — such as mask-border. It also interacts with properties that control how multiple masks are blended together; for example, the rules that determine whether the border mask adds to, subtracts from, or intersects the element’s main mask rely on compositing semantics similar to those governed by mask-composite. Finally, the element-level mask set by mask and any border mask are combined in a specified order, so the choice of mask-border-mode can change whether the border region remains visible, becomes partially transparent, or is removed entirely when all masks are applied.

In practical use, mask-border-mode is important when the mask image’s channel data could be interpreted in multiple ways (for instance a PNG with an alpha channel versus a grayscale image intended as a luminance mask) or when you need precise control over how the border’s visual mask blends with other masks and the element’s background. Designers use it to get crisp edges on decorative frames, to preserve alpha-based antialiasing, or to achieve soft transitions at the border independent of the interior mask. Because such blending and per-pixel interpretation can affect both visual fidelity and rendering cost, it’s also a consideration for performance when you use complex or multiple masks on high-resolution elements.

Definition

Initial value: alpha
Applies to: all elements; In SVG, it applies to container elements excluding the <defs> element and all graphics elements
Inherited: no
Computed value: as specified
Animatable: yes
JavaScript syntax: object.style.maskBorderMode

Syntax

mask-border-mode: alpha | luminance

Values

alphaThe default value. It uses the alpha channel (transparency) of the border image to create the mask. Opaque areas remain visible, and transparent areas are hidden.
luminanceUses the brightness (RGB values) of the border image to create the mask. White or light areas remain visible, while black or dark areas become transparent.

Example

HTML

<div class="container">

  <h2>mask-border-mode: alpha vs luminance</h2>

  <div class="row">

    <figure class="card alpha">

      <div class="content">Alpha</div>

      <figcaption>mask-border-mode: alpha</figcaption>

    </figure>

    <figure class="card luminance">

      <div class="content">Luminance</div>

      <figcaption>mask-border-mode: luminance</figcaption>

    </figure>

  </div>

</div>

CSS

:root {
  /* simple SVG ring used as a mask-border source (data URL) */
  --mask-svg: url('data:image/svg+xml;utf8,');
}

/* Layout */
.container {
  font-family: system-ui, -apple-system, 'Segoe UI', Roboto, 'Helvetica Neue', Arial;
  padding: 28px;
  background: #f6f7fb;
  min-height: 100vh;
  box-sizing: border-box;
}

.row {
  display: flex;
  gap: 20px;
  margin-top: 18px;
}

figure {
  margin: 0;
}

/* Card base styles + mask-border setup */
.card {
  width: 220px;
  height: 140px;
  display: flex;
  align-items: center;
  justify-content: center;
  border-radius: 8px;
  color: white;
  position: relative;
  box-sizing: border-box;

  /* mask-border properties (include -webkit- prefix for broader support) */
  -webkit-mask-border-source: var(--mask-svg);
  mask-border-source: var(--mask-svg);

  -webkit-mask-border-slice: 18;
  mask-border-slice: 18;

  -webkit-mask-border-width: 18px;
  mask-border-width: 18px;

  -webkit-mask-border-repeat: stretch;
  mask-border-repeat: stretch;

  /* default mode (overridden per card) */
  -webkit-mask-border-mode: alpha;
  mask-border-mode: alpha;
}

.card.alpha {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  -webkit-mask-border-mode: alpha;
  mask-border-mode: alpha;
}

.card.luminance {
  background: linear-gradient(135deg, #f6d365 0%, #fda085 100%);
  -webkit-mask-border-mode: luminance;
  mask-border-mode: luminance;
}

.content {
  font-weight: 700;
  font-size: 18px;
  text-shadow: 0 1px 0 rgba(0,0,0,0.12);
}

figcaption {
  font-size: 13px;
  color: #333;
  text-align: center;
  margin-top: 10px;
}

Result

Editor

Browser Support

The following information will show you the current browser support for the CSS mask-border-mode property. Hover over a browser icon to see the version that first introduced support for this CSS property.