HTML Guides for mask

The mask CSS shorthand property allows you to hide parts of an element by masking or clipping it at specific points. It combines several longhand properties into one declaration: mask-image, mask-mode, mask-repeat, mask-position, mask-clip, mask-origin, mask-size, and mask-composite.

Because mask is a shorthand that accepts values for many sub-properties, it’s easy to trigger validation errors. Common causes include:

• Too many values: Providing more values than the shorthand grammar allows, or duplicating values for the same sub-property.
• Unrecognized values: Using vendor-specific values (like -webkit- prefixed keywords), typos, or values that belong to a different CSS property.
• Incorrect value order: The shorthand has a specific grammar. For example, mask-size values must follow mask-position values and be separated by a /, similar to the background shorthand.
• Mixing shorthand and longhand concepts: Trying to set values that aren’t part of the mask shorthand grammar.

The formal syntax for a single mask layer is:

<mask-layer> = <mask-reference> || <position> [ / <bg-size> ]? || <repeat-style> ||
               <geometry-box> || [ <geometry-box> | no-clip ] || <compositing-operator> ||
               <masking-mode>

This is a problem for standards compliance because invalid CSS can lead to the entire declaration being ignored by browsers, causing your masking effect to silently fail. It also affects cross-browser compatibility — different browsers have varying levels of support for the mask shorthand, and using individual longhand properties is often more reliable.

To fix this issue:

1. Check each value in your mask declaration and ensure it’s a valid value for one of the mask sub-properties.
2. Use longhand properties instead of the shorthand if you only need to set one or two aspects of the mask. This avoids ambiguity and improves readability.
3. Separate position and size with / if you’re specifying both, e.g., center / contain.
4. Remove or separate vendor prefixes — use -webkit-mask for WebKit-specific syntax and the standard mask for standards-compliant syntax, but don’t mix prefixed values into the unprefixed property.

Examples

Incorrect: too many or unrecognized values in the shorthand

<style>
  .masked {
    /* Error: too many values / unrecognized combination */
    mask: url(mask.svg) center center no-repeat contain;
  }
</style>
<div class="masked">Content</div>

Here, contain is a mask-size value but it must be separated from the position with a /. Without the slash, the validator sees an extra unrecognized value.

Correct: proper shorthand syntax with position and size

<style>
  .masked {
    mask: url(mask.svg) center / contain no-repeat;
  }
</style>
<div class="masked">Content</div>

The / separates mask-position (center) from mask-size (contain), just like in the background shorthand.

Correct: using longhand properties for clarity and compatibility

<style>
  .masked {
    width: 100px;
    height: 100px;
    background-color: #8cffb0;
    -webkit-mask-image: url(sun.svg);
    mask-image: url(sun.svg);
    mask-repeat: no-repeat;
    mask-position: center;
    mask-size: contain;
  }
</style>
<div class="masked">Content</div>

Using individual longhand properties avoids shorthand parsing issues entirely. Including the -webkit-mask-image prefix alongside the standard mask-image ensures broader browser support.

Incorrect: unrecognized value in the shorthand

<style>
  .masked {
    /* "luminance" is a mask-mode value but may not be recognized in the shorthand by all validators */
    mask: url(mask.png) luminance;
  }
</style>
<div class="masked">Content</div>

Correct: using the longhand for mask mode

<style>
  .masked {
    mask-image: url(mask.png);
    mask-mode: luminance;
  }
</style>
<div class="masked">Content</div>

When in doubt, splitting the mask shorthand into its individual longhand properties is the safest approach. It makes your intent explicit, avoids validation errors, and tends to have better cross-browser support.

The mask CSS shorthand property allows you to partially or fully hide portions of an element by applying a graphical mask. It is a shorthand for several sub-properties including mask-image, mask-mode, mask-repeat, mask-position, mask-clip, mask-origin, mask-size, and mask-composite. Because it’s a shorthand, each value you provide must correspond to one of these sub-properties’ accepted values. The validator triggers this error when it encounters a value that doesn’t fit any of them — for example, an arbitrary keyword, a misspelled function name, or an unsupported syntax.

Common causes of this error include:

• Arbitrary keywords — Using made-up names like star-shape or circle-mask that aren’t valid CSS values.
• Misspelled functions or keywords — Typos such as lnear-gradient() instead of linear-gradient(), or noen instead of none.
• Browser-prefixed values without the standard value — Using -webkit-mask syntax or values that don’t align with the standard mask property.
• Invalid shorthand combinations — Providing sub-property values in an order or combination the shorthand doesn’t accept.
• Missing url() wrapper — Referencing an image file path directly without wrapping it in the url() function.

This matters for standards compliance because browsers may silently ignore invalid mask values, resulting in the mask not being applied at all. Your design could look completely different than intended, and the failure may be hard to debug without validation.

Valid mask values

The mask property accepts one or more comma-separated mask layers. Each layer can include:

• none — No mask is applied.
• url() — A reference to an SVG mask element or an image file (e.g., url(mask.svg), url(mask.png)).
• CSS image functions — Such as linear-gradient(), radial-gradient(), conic-gradient(), image(), etc.
• Geometry box keywords (for mask-clip / mask-origin) — Such as content-box, padding-box, border-box, fill-box, stroke-box, view-box.
• Compositing keywords (for mask-composite) — Such as add, subtract, intersect, exclude.

Examples

Incorrect: arbitrary keyword as a mask value

<div style="mask: star-shape;">
  Masked Content
</div>

The value star-shape is not a recognized mask value and will be rejected by the validator.

Incorrect: missing url() function

<div style="mask: star.svg;">
  Masked Content
</div>

A bare file path is not valid. Image references must be wrapped in the url() function.

Correct: using url() to reference a mask image

<div style="mask: url(star.svg);">
  Masked Content
</div>

Correct: using none to explicitly disable masking

<div style="mask: none;">
  No Mask Applied
</div>

Correct: using a gradient as a mask

<div style="mask: linear-gradient(to right, transparent, black);">
  Fading Content
</div>

Correct: combining multiple shorthand values

<div style="mask: url(mask.png) no-repeat center / contain;">
  Masked Content
</div>

This sets the mask image, repeat behavior, position, and size in a single shorthand declaration.

Correct: multiple mask layers

<div style="mask: url(shape.svg) no-repeat, linear-gradient(to bottom, black, transparent);">
  Multi-layer Mask
</div>

When fixing this error, double-check your value against the CSS Masking specification on MDN. If you’re using vendor-prefixed versions like -webkit-mask, also ensure the standard mask property is present with valid values for forward compatibility.