Skip to main content
XenonStack

Service Design

XenonStack Insights CSS Mask Image: Syntax, Values and Examples

and | Published | Updated

CSS mask-image explained: a stack from mask-image source through mask-mode and mask-composite to the visible, faded result.

Key takeaway

  • Learn how CSS mask-image works: alpha and luminance masks, mask-composite, mask-clip, gradient fades and text effects, checked against the MDN docs.

CSS masking hides parts of an element by painting it through a second image, a gradient or an SVG mask. The mask-image property supplies that mask: where the mask is opaque the element shows, where the mask is transparent the element is hidden, and values in between give a partial fade.

This guide covers the properties you need (mask-image, mask-mode, mask-clip, mask-origin and mask-composite), gradient fades, text effects, animation limits and the points where masks fail silently. Every value and default below is taken from the MDN Web Docs pages listed at the end. For the shape-based alternative, see our post on CSS mask and clip-path.

What is CSS masking and how does it differ from clipping?

According to MDN, the CSS masking module defines masking and clipping, two different graphical operations used to partially or fully hide portions of visual elements. Clipping defines a closed vector path or shape: everything inside stays visible and everything outside is clipped out. Masking paints a mask image over the element, so the opacity or luminance of the mask decides how much of the element shows.

MDN also notes that masking gives more control and options, while clipping can perform better when a basic shape is all you need, because basic shapes are easier to interpolate. When both are applied, the browser handles filter effects first, then clipping, then masking, then opacity.

NeedBetter fitWhy
A hard-edged shape such as a circle or polygonclip-pathA basic shape is enough, and MDN says clipping can perform better for that case.
A soft fade or feathered edgemask-image with a gradientPartial transparency in the mask gives partial visibility in the element.
A logo or icon cut-out with detailmask-image with an image or SVGThe mask can be any image, gradient or SVG mask element.
Combining several shapesmask-image layers with mask-compositeLayers can be added, subtracted, intersected or excluded.

How do alpha and luminance masks work?

The alpha channel of the mask always matters. MDN states that element areas masked by opaque sections of the mask-image are rendered, while areas masked by transparent sections are hidden. The mask-mode property then decides what the browser reads from each colour.

Two-column diagram: mask-image, mask-mode, mask-clip and mask-composite on the left, with the source, channel read, box and compositing operator each controls on the right.
  • Alpha mode: only the alpha channel counts. Hue and lightness do not matter.
  • Luminance mode: the mask value is the luminance of each colour multiplied by its alpha. White shows the element, black hides it, and greys give partial visibility.
  • Match-source (the default): the mode comes from the mask image itself. It is generally alpha, except when the source is an SVG <mask> element, where it is luminance (unless changed with mask-type).

This is the reverse of what many older tutorials say. A transparent area of the mask hides the element; it does not reveal "the image below".

Which CSS mask properties should you know?

The longhand properties below control one aspect of the mask each. The mask shorthand sets them together, and the module also includes mask-repeat, mask-position, mask-size, mask-type and the mask-border family.

PropertyWhat it controlsAccepted values (MDN)Initial value
mask-imageThe image, gradient or SVG mask usednone, a url() to an image or SVG <mask>, or an image value such as a gradient; comma-separated for several layersnone
mask-modeWhether alpha or luminance is readalpha, luminance, match-sourcematch-source
mask-clipThe area of the element the mask can paint intocontent-box, padding-box, border-box, fill-box, stroke-box, view-box, no-clipborder-box
mask-originThe box the mask position is measured fromcontent-box, padding-box, border-box, fill-box, stroke-box, view-boxborder-box
mask-compositeHow stacked mask layers combineadd, subtract, intersect, excludeadd

margin-box is not a valid value for mask-clip or mask-origin. Many older guides list it, but it does not appear in the MDN syntax for either property. MDN lists mask-image, mask-clip, mask-origin and mask-composite as widely available across browsers since December 2023, with a note that some parts of each feature may have varying levels of support. Check the compatibility table on each MDN page before relying on a specific value.

How do you fade an image with a gradient mask?

A gradient is the quickest mask because it needs no image file. In the example below the element is fully hidden at the top and fully visible at the bottom, with a smooth fade between.

.fade-bottom {
  mask-image: linear-gradient(to bottom, transparent 25%, black 75%);
}

The colour black here is only a stand-in for "opaque". In alpha mode any fully opaque colour gives the same result. Some projects still add a -webkit-mask-image line for older WebKit-based browsers; decide that from the MDN compatibility table and your own browser support policy, not from habit.

Several masks can be stacked by separating them with commas, and each layer can have its own size, position and repeat settings:

img {
  mask-size: 95%, 100%;
  mask-position: center;
  mask-repeat: no-repeat;
  mask-image:
    url("mask-star.svg"),
    repeating-radial-gradient(transparent 0 5px, black 5px 10px);
}

How do mask layers combine with mask-composite?

When mask-image has more than one layer, mask-composite sets how each layer is combined with the layers beneath it. The values are Porter-Duff compositing operators. MDN defines them as follows.

ValueResult (MDN wording, shortened)
add (default)The layer is placed over all layers below it.
subtractThe layer is placed only where it falls outside the layers below it.
intersectOnly the parts of the layer that overlap the layers below it are kept, and they replace those layers.
excludeThe non-overlapping regions of the layer and the layers below it are combined.

If there are fewer mask-composite values than mask layers, the list repeats until every layer has one.

Can you mask text with CSS?

There are two different things people mean. The first is masking an element that contains text, for example fading a paragraph out at the bottom of a card. This uses the same gradient technique as for images and works on any element.

.card-text {
  mask-image: linear-gradient(to bottom, black, transparent);
}

The second is using the text as the shape. MDN lists a text keyword for mask-clip that clips the mask image to the text of the element, but it appears in the values list and not in the formal syntax. Treat it as an area to test and confirm on the MDN page and its compatibility table before using it in production.

Can you animate a CSS mask?

MDN gives the animation type of mask-image and mask-composite as discrete. That means the browser switches between values and does not blend smoothly from one gradient to another. If you need a smooth reveal, test which mask-related properties are animatable on their MDN pages, and keep the effect short and optional for users who prefer reduced motion.

Why does my mask show nothing?

A mask that cannot be used is treated as transparent black, which hides the element. MDN lists these cases: the mask image is empty (zero width or height), fails to download, is in a format the browser does not support, does not exist, or the value does not point to a mask image. For URL sources, MDN notes that only images served over HTTP and HTTPS are accepted because of the CORS policy; local files, including file:// paths, render as transparent black. Test masks from a local web server, not from a file opened directly.

What does this mean for enterprise front-end teams?

Masks are a visual detail, so the decision is mostly about maintenance. Keep mask definitions in shared design tokens or component styles, record the browser support you test against, and use clip-path where a basic shape is enough. Heavy decorative effects on large images are worth checking with your normal performance tooling; see our posts on the CSS content-visibility property, code-splitting in React and fluid typography with CSS clamp.

Teams building interfaces for AI agents, such as review consoles and approval screens, face the same discipline at a larger scale: ElixirClaw is an agentic OS platform to build, orchestrate and govern AI agents and automation workflows while keeping humans in control, and ElixirData Context OS keeps governed context, versioned policy and decision traces in one decision layer above AI agents.

To map one front-end or interface decision your agents should make, and the context and policy it depends on, book a Context Workshop. See what happens in the workshop.

Frequently asked questions

What does mask-image do in CSS?

It sets one or more images, gradients or SVG masks that decide which parts of an element are visible. Opaque parts of the mask show the element and transparent parts hide it. The initial value is none.

What is the difference between an alpha mask and a luminance mask?

An alpha mask reads only the alpha channel of the mask. A luminance mask reads the luminance of each colour multiplied by its alpha. By default, mask-mode is match-source, which is alpha for most images and luminance for SVG <mask> elements.

Is margin-box a valid value for mask-clip or mask-origin?

No. According to MDN, both properties accept content-box, padding-box, border-box, fill-box, stroke-box and view-box, and mask-clip also accepts no-clip. The initial value of both is border-box.

What are the mask-composite values?

The values are add (the default), subtract, intersect and exclude. They set how a mask layer is combined with the layers below it.

Should I use mask-image or clip-path?

Use clip-path for a basic shape with hard edges, since MDN notes clipping can perform better there. Use mask-image for soft fades, detailed cut-outs and layered effects.

Sources

Table of Contents

navdeep-singh-gill

Navdeep Singh Gill

Global CEO and Founder of XenonStack

LinkedIn profile

Navdeep Singh Gill is serving as Chief Executive Officer and Product Architect at XenonStack. He holds expertise in building SaaS Platform for Decentralised Big Data management and Governance, AI Marketplace for Operationalising and Scaling. His incredible experience in AI Technologies and Big Data Engineering thrills him to write about different use cases and its approach to solutions.

Get the latest articles in your inbox

Subscribe Now

Interested in solving your challenges with the XenonStack team?
Get Started

Tell us about you and your priorities so we can prepare the right conversation. It takes about 2 minutes.

Please Select your Industry
Banking
Fintech
Payment Providers
Wealth Management
Discrete Manufacturing
Semiconductor
Machinery Manufacturing / Automation
Appliances / Electrical / Electronics
Elevator Manufacturing
Defense & Space Manufacturing
Computers & Electronics / Industrial Machinery
Motor Vehicle Manufacturing
Food and Beverages
Distillery & Wines
Beverages
Shipping
Logistics
Mobility (EV / Public Transport)
Energy & Utilities
Hospitality
Digital Gaming Platforms
SportsTech with AI
Public Safety - Explosives
Public Safety - Firefighting
Public Safety - Surveillance
Public Safety - Others
Media Platforms
City Operations
Airlines & Aviation
Defense Warfare & Drones
Robotics Engineering
Drones Manufacturing
AI Labs for Colleges
AI MSP / Quantum / AGI Institutes
Retail Apparel and Fashion

Continue