CSS mask-image Property

What You’ll Learn

The mask-image property defines an image or gradient mask that controls which parts of an element stay visible — ideal for soft fades, custom silhouettes, and creative visual effects.

Introduction

The mask-image property in CSS allows you to define an image as a mask for an element. It can partially or fully hide parts of the element’s content based on the mask’s transparency.

Masks work by controlling the visibility of each pixel: a transparent mask pixel hides the corresponding part of the element, and an opaque mask pixel keeps it visible. This is especially useful for complex visual effects and shapes without extra SVG markup.

Definition and Usage

Apply mask-image when you want soft edges, image-based silhouettes, or gradient fades. Pair it with related properties like mask-size and mask-repeat to position and scale the mask.

📝 Syntax

The syntax for the mask-image property allows URLs to images, CSS gradients, and the keyword none:

element {
  mask-image: value;
}

Basic Example

.masked-image {
  width: 300px;
  height: 300px;
  background-image: url('/images/valley-pattern.jpg');
  -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;
}

Syntax Rules

• The initial value is none (no mask applied).
• url() points to a PNG, SVG, or other image used as the mask layer.
• Gradients like linear-gradient() and radial-gradient() create soft masks without image files.
• Include -webkit-mask-image alongside mask-image for broader Safari support.
• Often combined with mask-size, mask-position, and mask-repeat.

💎 Property Values

The mask-image property accepts image URLs, gradients, or none.

🎯 Default Value

The default value of the mask-image property is none, meaning no mask is applied and the element is fully visible.

Common Mask Sources

Examples Gallery

Mask a background with a PNG image, create gradient fades, build radial spotlights, and compare masking with clipping.

<style>
  .masked-image {
    width: 300px;
    height: 300px;
    background-image: url('/images/valley-pattern.jpg');
    background-size: 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;
  }
</style>

<div class="masked-image"></div>

<style>
  .fade-box {
    width: 240px;
    height: 160px;
    background: linear-gradient(135deg, #6366f1, #8b5cf6);
    -webkit-mask-image: linear-gradient(to bottom, #000 30%, transparent);
    mask-image: linear-gradient(to bottom, #000 30%, transparent);
  }
</style>

<div class="fade-box"></div>

<style>
  .spotlight {
    width: 220px;
    height: 160px;
    background: linear-gradient(135deg, #16a34a, #059669);
    -webkit-mask-image: radial-gradient(circle, #000 35%, transparent 72%);
    mask-image: radial-gradient(circle, #000 35%, transparent 72%);
  }
</style>

<div class="spotlight"></div>

/* Soft gradient mask */
.masked {
  mask-image: linear-gradient(to right, #000, transparent);
}

/* Hard geometric clip */
.clipped {
  clip-path: circle(50%);
}

♿ Accessibility

• Do not hide essential content — Masked-away text or controls may be invisible but still exist in the DOM.
• Provide alt text for images used as visible content, even when masked decoratively.
• Test contrast — Gradient fades can reduce readability if text sits over masked areas.
• Check pointer events — Hidden mask areas may still receive clicks unless you adjust interaction.
• Offer fallbacks — Ensure content remains usable when masking is unsupported.

mask-image vs clip-path

💡 Best Practices