A plain custom property is an untyped token list that inherits everywhere and starts as the guaranteed-invalid value. @property turns it into something close to a built-in property:
@property --angle {
syntax: "<angle>";
inherits: false;
initial-value: 0deg;
}
What that buys:
- Animation. Transitions and keyframes interpolate it by its type. Unregistered,
--anglefrom0degto360degis discrete; registered, it passes through90deg. That's how you animate a gradient angle or a colour stop, which can't be animated directly. - A computed type.
--x: 8emwithfont-size: 10pxcomputes to80px, so children inherit a length, not tokens to re-resolve. - A real initial value. The property is never guaranteed-invalid, so a
var()fallback never applies: withinitial-value: 4pxand nothing set,var(--size, 99px)gave4px. - Control of inheritance. With
inherits: false, a value set on a parent doesn't reach its children; they get the initial value. - Type checking, late. The syntax is checked at computed-value time, not parse time: a wrong value still wins the cascade, then makes the custom property itself act as
unset. Its inherited or initial value is substituted, so the property using it gets a valid value.
The rule is strict. syntax and inherits are required; initial-value is required unless the syntax is "*", and it must be computationally independent: 1em or var(--x) are rejected. An invalid rule is dropped whole, and the property stays unregistered.
Registrations are document-global, even from a shadow tree. The last @property wins; CSS.registerProperty() beats both. Support: Chrome 85, Firefox 128, Safari 16.4.