Registering custom properties in CSS

The CSS @property rule is a newer addition to the platform, currently on its way to Chrome with active development in the Houdini task force. It provides a stylesheet-based way to declare custom properties with type information, serving as the CSS equivalent of the JavaScript CSS.registerProperty() API.

@property --my-property {
  syntax: "<color>";
  initial-value: green;
  inherits: false;
}

Unlike normal custom property declarations, @property is not written inside a selector block. It sits at the top level, similar to an @media rule. The rule itself doesn’t create a property instance; it registers the property’s type so that later usage inside selectors can be treated with that type in mind.

What type registration unlocks

A frequently cited example is animating gradients. Without registration, the browser has no way to know whether a custom property holds a color or something else, so interpolating it as part of a gradient transition simply doesn’t work:

.el {
  background: linear-gradient(white, black);
  /* this transition won't work */
  transition: 1s;
}
.el:hover {
  background: linear-gradient(red, black);
}

Previously, achieving that effect required workarounds such as layering a pseudo-element with the destination gradient and fading its opacity, or positioning a wider background to fake a transition. With a registered property, the declaration becomes:

@property --gradient-start {
  syntax: "<color>";
  initial-value: white;
  inherits: false;
}

.el {
  --gradient-start: white;
  background: linear-gradient(var(--gradient-start), black);
  transition: --gradient-start 1s;
}

.el:hover {
  --gradient-start: red;
}

Because @property tells the CSS engine the custom property is a <color>, it can now be animated and interpolated the same way any other color value would be.

This is reminiscent of the limitation with attr(), where pulling a value like data-size="22px" yields a string, not a usable <length> — though a future syntax like attr(data-size px) has been floated as a possibility.

Timing for broad availability remains unclear, though Chrome is expected to ship first, with encouraging signals coming from Safari and Firefox.