CSS mask-image Property

Beginner
5 min read
Updated: Oct 2026
3 examples
Live preview

Definition and Usage

The mask-image property sets the image used as a mask layer. Opaque parts of the mask keep the element visible; transparent parts hide it. Gradients and url() images both work.

It is not inherited. The initial value is none. Pair it with mask-mode, mask-size, and mask-repeat when you need more control.

Standard-track · Baseline Widely available.

Not deprecated. Unprefixed mask-image is Baseline since December 2023. Keep -webkit-mask-image for older WebKit and Chromium. SVG <mask> sources often use luminance; set mask-mode when alpha-only masking is required.

CSS Syntax

syntax.css
mask-image: none | <image> | <mask-source> | initial | inherit;

You can list multiple masks separated by commas. <image> includes gradients and url().

Property Values

ValueDescriptionTry it
noneDefault. No mask; the element is fully visibleTry it
<gradient>A CSS gradient used as the mask (great for fades)Try it
radial-gradient()Soft circular or spotlight-style masksTry it
url()An image or SVG used as the mask layerTry it
initialResets to noneTry it
inheritTakes the parent’s mask-imageTry it

How to Use mask-image

Think of the mask as a stencil: black/opaque shows content; transparent hides it.

  1. Choose a target element (image, box, or text container).
  2. Set mask-image to a gradient or url(...).
  3. For image masks, add mask-size / mask-repeat so the shape fits.
  4. Duplicate with -webkit-mask-image when older Safari or Chromium matter.
PieceRequired?Role
Element to maskYesThe painted content that will be clipped by the mask
mask-image valueYesnone, gradient, or url()
mask-size / mask-repeatFor imagesStop tiling and size the mask correctly
-webkit-mask-imageRecommendedBroader support on older engines

Live Preview

Switch the mask on the sample box. Opaque mask areas keep the gradient visible.

Black / opaque mask = visible. Transparent mask = hidden.

Box

mask-image: linear-gradient fade

CSS Examples

Each snippet focuses on mask-image. Use Try It Yourself for a live editor.

Example 1 — Linear Gradient Fade

Fade a box from solid to invisible with a linear mask.

CSS
<style>
  div {
    width: 220px;
    height: 140px;
    background: linear-gradient(135deg, #6366f1, #ec4899);
    mask-image: linear-gradient(to bottom, #000 30%, transparent);
  }
</style>

<div></div>
Try It Yourself

How It Works

  1. Paint a box. The gradient background is what you want to reveal.
  2. Add a linear mask. #000 (opaque) keeps the top visible.
  3. Fade to transparent. Lower parts of the mask hide the box.
  4. No image file needed. Gradients make soft masks without assets.

Example 2 — Radial Soft Edge

Use a radial gradient for a soft circular spotlight.

CSS
<style>
  div {
    width: 220px;
    height: 140px;
    background: linear-gradient(135deg, #16a34a, #059669);
    mask-image: radial-gradient(circle, #000 40%, transparent 70%);
  }
</style>

<div></div>
Try It Yourself

How It Works

  1. Start opaque in the center. #000 40% keeps the middle visible.
  2. Fade outward. transparent 70% softens the edge.
  3. Softer than clip-path. clip-path would cut a hard circle.
  4. Tune the stops. Move the percentages to change how sharp the falloff feels.

Example 3 — Image URL Mask

Use a PNG silhouette as the mask shape over a photo background.

CSS
<style>
  div {
    width: 220px;
    height: 140px;
    background: url("/images/valley-pattern.jpg") center / cover;
    mask-image: url("/images/apple.png");
    mask-size: contain;
    mask-repeat: no-repeat;
    mask-position: center;
  }
</style>

<div></div>
Try It Yourself

How It Works

  1. Set the photo as background. That is the content being masked.
  2. Point mask-image at a PNG. Opaque pixels of the PNG reveal the photo.
  3. Size and center it. contain + no-repeat keep one clean shape.
  4. Serve over HTTP(S). file:// mask URLs fail CORS and look fully hidden.

Edge Cases & Pitfalls

Most “invisible” masks come from bad URLs, tiling, or luminance rules.

cors

Local file:// masks fail

Mask images must load over HTTP or HTTPS. A missing or blocked URL becomes a transparent black layer and hides everything.

repeat

Image masks tile by default

Without mask-repeat: no-repeat and a sensible mask-size, a small PNG can repeat across the box.

luminance

SVG <mask> uses luminance

White shows, black hides. Colors matter unless you set mask-mode: alpha.

prefix

Older engines need -webkit-

Write both -webkit-mask-image and mask-image when supporting browsers before the unprefixed Baseline.

Browser Support

mask-image is a browser CSS property. Node.js, Deno, and Bun do not apply it.

✓ Baseline · Widely available since Dec 2023

mask-image

Unprefixed: Chrome 120+, Edge 120+, Firefox 53+, Safari 15.4+, Opera 106+. Prefixed -webkit-mask-image works in much older WebKit/Blink. Internet Explorer has no support.

97% Global reach
Google Chrome 120+
Full support
Mozilla Firefox 53+
Full support
Apple Safari 15.4+
Full support
Microsoft Edge 120+
Full support
Opera 106+
Full support
Samsung Internet 25.0+
Full support
Internet Explorer No support
Not supported
mask-image Widely supported

Bottom line: Safe for modern sites. Keep -webkit-mask-image for older Safari and Chromium. Skip Internet Explorer. This is browser layout CSS, not a server runtime API.

Key Takeaways

  • Role: hide parts of an element using an image or gradient mask.
  • Common values: none, gradients, and url().
  • Initial value: none. Not inherited.
  • Tip: opaque mask = visible; transparent mask = hidden.

One line: mask-image is a stencil — use gradients or images to show and hide parts of a box.

Frequently Asked Questions

It sets an image or gradient used as a mask. Opaque areas of the mask keep the element visible; transparent areas hide it.
The initial value is none. No mask is applied and the element stays fully visible.
clip-path cuts a hard geometric shape. mask-image uses alpha (and sometimes luminance) from an image or gradient, so fades and soft edges are easy.
Yes. linear-gradient() and radial-gradient() are common masks for fades and soft circles without extra image files.
Unprefixed mask-image is Baseline. Keep -webkit-mask-image as well when you need older WebKit and Chromium engines.
It is Baseline and widely available. Unprefixed support: Chrome 120+, Edge 120+, Firefox 53+, Safari 15.4+. Prefixed support is older. Internet Explorer does not support it. It is a browser CSS property, not a Node.js feature.

Next: mask-mode

Learn when a mask uses alpha channels versus luminance.

mask-mode tutorial →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

5 people found this page helpful