syntax

Baseline 2024

Newly available

Since July 2024, this feature works across the latest devices and browser versions. This feature might not work in older devices or browsers.

The syntax descriptor of the @property at-rule defines the allowed value types for the registered CSS custom property. It controls how the property's specified value is processed to derive the computed value. It is a required descriptor; if missing or invalid, the entire @property rule is invalid and ignored.

Syntax

css

/* A data type name */
syntax: "<color>";

/* A '|' combinator for multiple data types */
syntax: "<length> | <percentage>";

/* Space-separated list of values */
syntax: "<color>+";

/* Comma-separated list of values */
syntax: "<length>#";

/* Keywords */
syntax: "small | medium | large";

/* Combination of data type and keyword */
syntax: "<length> | auto";

/* Universal syntax value */
syntax: "*";

Values

A string (known as the syntax string) that defines the allowed values. It can be one of the following:

One or more syntax component names, which can be:
- Data type names (written with angle brackets, such as <color> or <length>)
- Keywords (written without angle brackets, such as auto or none)
The universal syntax *, which accepts any valid CSS value. It cannot be multiplied or combined with other syntax components.

The syntax component names can be used alone or multiplied and combined in different ways:

The + (space-separated) and # (comma-separated) multipliers indicate that a list of values is expected. For example, <color># means a comma-separated list of <color> values is the expected syntax.
The vertical line (|) combinator can create "or" conditions for the expected syntax. For example, <length> | auto accepts <length> or auto, and <color># | <integer># expects a comma-separated list of <color> values or a comma-separated list of <integer> values.

The following syntax component names are supported:

"<angle>": Accepts any valid <angle> value.
"<color>": Accepts any valid <color> value.
"<custom-ident>": Accepts any valid <custom-ident> value.
"<image>": Accepts any valid <image> value.
"<integer>": Accepts any valid <integer> value.
"<length>": Accepts any valid <length> value.
"<length-percentage>": Accepts any valid <length> or <percentage> value and any valid calc() expression combining <length> and <percentage> values.
"<number>": Accepts any valid <number> value.
"<percentage>": Accepts any valid <percentage> value.
"<resolution>": Accepts any valid <resolution> value.
"<string>": Accepts any valid <string> value.
"<time>": Accepts any valid <time> value.
"<transform-function>": Accepts any valid <transform-function> value.
"<transform-list>": Accepts a list of valid <transform-function> values. It is equivalent to "<transform-function>+".
"<url>": Accepts any valid <url> value.

Formal definition

Related at-rule	`@property`
Initial value	`n/a (required)`
Computed value	as specified

Formal syntax

syntax = 
  <string>

Examples

Registering a custom property with type checking

This example shows how to define a custom property --my-color that allows only <color> values:

css

@property --my-color {
  syntax: "<color>";
  inherits: false;
  initial-value: #c0ffee;
}

Using JavaScript CSS.registerProperty():

window.CSS.registerProperty({
  name: "--my-color",
  syntax: "<color>",
  inherits: false,
  initialValue: "#c0ffee",
});

Specifications

Specification
CSS Properties and Values API Level 1 # the-syntax-descriptor

Browser compatibility

BCD tables only load in the browser