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
/* 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
ornone
)
- Data type names (written with angle brackets, such as
-
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>
orauto
, 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 validcalc()
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:
@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
See also
- Other
@property
descriptors:inherits
andinitial-value
- CSS Properties and Values API
- CSS Painting API
- CSS Typed Object Model
- Houdini APIs