# CSS: “mask”: Too many values or values are not recognized.

> Canonical HTML version: https://rocketvalidator.com/html-validation/css-mask-too-many-values-or-values-are-not-recognized
> Attribution: Rocket Validator (https://rocketvalidator.com)
> License: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/)

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

```html
<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

```html
<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

```html
<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

```html
<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

```html
<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.