Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท At-rules

The @property at-rule

Reference for the CSS @property at-rule: register a custom property with a syntax, initial value and inheritance, so it can be validated and animated.

The @property at-rule registers a custom property. A plain --x property is just a string of tokens; a registered one has a type (<length>, <color>, <angle>...), an initial value and a choice of whether it inherits.

The type is what makes the difference: the browser can validate values, resolve units like em, and most importantly interpolate the value, so transitions and animations on a custom property become smooth. An unregistered property jumps between values.

CSS
@property --angle {
  syntax: "<angle>";
  inherits: false;
  initial-value: 0deg;
}

Try it

Animate a gradient angle

Syntax

CSS
@property --name {
  syntax: "<type>";
  inherits: true | false;
  initial-value: <value>;
}
  • syntax (required): a string such as "<length>", "<number>", "<percentage>", "<color>", "<angle>", "<length-percentage>", "<image>", a list with + or # ("<length>+"), keyword alternatives ("small | large"), or "*" for anything.
  • inherits (required): whether descendants inherit the value.
  • initial-value: required unless syntax is "*"; it must be computationally independent (10px is fine, 2em is not).
  • The JavaScript equivalent is CSS.registerProperty({ name, syntax, inherits, initialValue }).

Values

Syntax and arguments Description
syntax: "<length>" Accepts lengths; interpolates between them.
syntax: "<color>" Accepts colours; animates in the colour space.
syntax: "<number>" Numbers; useful for counters and scale factors.
syntax: "<angle>" Degrees, turns, etc.; good for gradient angles.
syntax: "*" Universal; no typing and no interpolation.
inherits: false Each element starts from the initial value.
initial-value: 0px Value used when none is set.

Usage notes

  • Registered properties validate. An invalid value (--size: red for a <length>) is discarded and the property falls back to its initial value or inherited value.
  • Choose inherits: false unless you need the value in children; it is cheaper for the browser.
  • Used with transitions. transition: --angle 0.4s; works once the property is registered.
  • Define it once at the top level; duplicate registrations after the first are ignored.
  • Counting trick. A registered <integer> custom property can be animated and displayed with counter-reset and content: counter(...).
  • The unit is resolved at computed time, so a <length> of 2em becomes pixels where it is set.

Browser support

Baseline since July 2024 (Chrome and Edge 85, Safari 16.4, Firefox 128).