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.
@property --angle { syntax: "<angle>"; inherits: false; initial-value: 0deg; }
Try it
Syntax
@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 unlesssyntaxis"*"; it must be computationally independent (10pxis fine,2emis 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: redfor a<length>) is discarded and the property falls back to its initial value or inherited value. - Choose
inherits: falseunless 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 withcounter-resetandcontent: counter(...). - The unit is resolved at computed time, so a
<length>of2embecomes pixels where it is set.
Browser support
Baseline since July 2024 (Chrome and Edge 85, Safari 16.4, Firefox 128).
Related
@keyframes@layer@supports- Lesson: Custom Properties
- Lesson: Animations