CSS custom properties get types, fallbacks, and animation support

CSS Houdini is an umbrella term for a set of low-level APIs that expose parts of the CSS rendering engine to developers. Among the most significant additions is the Properties and Values API, which gives CSS custom properties semantic meaning by defining a syntax, a fallback value, and an inheritance boolean.

The API can be used in two ways. In JavaScript via CSS.registerProperty() (supported in Chromium 78+):

CSS.registerProperty({
  name: '--colorPrimary',
  syntax: '<color>',
  initialValue: 'magenta',
  inherits: false
});

Or directly in CSS files with the @property rule (Chromium 85+):

@property --colorPrimary {
  syntax: '<color>';
  initial-value: magenta;
  inherits: false;
}

Once registered, you can access --colorPrimary with var(--colorPrimary) just like any other custom property. The difference is that the value is no longer parsed as a plain string — it carries data and can be type-checked.

Real fallback values

When you override a registered custom property with an invalid value, the CSS rendering engine substitutes the initial value instead of ignoring the declaration. This gives you genuine fallback behavior, not just error tolerance.

Consider a --colorPrimary variable with an initial-value of magenta. If the developer assigns 23, a regular custom property would cause the parser to discard the invalid line. With @property, the parser falls back to magenta — enabling defensible defaults and testing within CSS.

.card {
  background-color: var(--colorPrimary); /* magenta */
}

.highlight-card {
  --colorPrimary: yellow;
  background-color: var(--colorPrimary); /* yellow */
}

.another-card {
  --colorPrimary: 23;
  background-color: var(--colorPrimary); /* magenta */
}

Typed syntax for semantic CSS

The syntax feature lets you declare a type for a custom property. The currently supported types include:

  • length, number, percentage, length-percentage
  • color, image, url
  • integer, angle, time, resolution
  • transform-list, transform-function
  • custom-ident (a custom identifier string)

Typing enables the browser to validate custom properties at parse time, which unlocks practical benefits — most notably, smooth interpolation during animations.

Animating gradient stops

Without typed properties, there is no way to smoothly transition between gradient values because each gradient declaration is interpreted as a string. The browser on the left side of the comparison below supports the Properties and Values API and animates a gradient stop from 40% to 100% on hover. The browser on the right treats the change as a string operation, so no interpolation occurs.

Using a custom property with a "number" syntax, the gradient on the left shows a smooth transition between stop values. The gradient on the right uses a default custom property (no syntax defined) and shows an abrupt transition.

By declaring a typed custom property for the gradient point:

@property --gradPoint {
  syntax: '<percentage>';
  inherits: false;
  initial-value: 40%;
}

you can animate it by updating its value between the initial 40% and the hover target of 100%:

.post:hover,
.post:focus {
  --gradPoint: 100%;
}

The result is a smooth transition of the gradient stop:

Smoothly transitioning gradient borders. See Demo on CodePen

Bottom line

The @property rule makes Houdini's Properties and Values API far more approachable by bringing typed custom properties into CSS itself. For further reading, see Is Houdini Ready Yet?, the MDN Houdini Reference, and the Smarter custom properties with Houdini's new API article.