CSS custom properties get typed with @property

The CSS Houdini @property rule is now supported across all modern browsers, giving developers typed control over CSS custom properties. Where a standard custom property is parsed as a string, @property lets you declare a syntax type, an initial value, and inheritance behavior for any ---prefixed variable. The result is more predictable styling, safer fallbacks, and new animation capabilities that were previously impossible.

Why register a custom property?

Without registration, a custom property is just a string placeholder. Consider a variable that is expected to hold a color and is used elsewhere in the stylesheet. If that variable gets updated to a number, every rule depending on it will fail.

Registering the same variable with @property changes that picture:

  • Syntax validation: The syntax descriptor tells the browser the property can only hold a specific data type, such as a color, length, or number. Non-conforming values are rejected.
  • Graceful fallback: An initial-value can be set. When an invalid value is assigned at any point, the browser silently falls back to this declared initial value instead of breaking the style.
  • Inheritance control: The inherits descriptor explicitly sets whether the property cascades to descendants, preventing accidental leakage.

Animated gradients without workarounds

Gradients are rendered as images, so browsers won't interpolate between two different gradient definitions in a CSS transition. With typed custom properties, that limitation disappears.

If you define two custom properties as colors with @property, you can then reference them inside a gradient declaration. Animating those registered properties in a @keyframes rule produces a smooth gradient transition—something that previously required JavaScript or image swaps.

A practical example is a card whose background shifts between two radial gradients on independent timelines. Set up each color variable with a syntax of <color>, build the gradient by referencing those variables, and then update the variable values inside keyframes. Each property animates separately whenever its value changes, giving the background a twinkling effect.

Broader implications for CSS authoring

Typed custom properties extend CSS by adding semantics to variables. Beyond animations, this enables better error handling and validation directly inside the stylesheet, because the browser can now reason about the data a variable holds.

For more background, the MDN CSS Houdini reference and the earlier web.dev article on @property offer additional examples and details.