CSS Houdini

A regular CSS custom property consists of a property name and a value. Therefore I might create a custom property called --background-color and expect it to be given a color value. The value is then used in the CSS as if it were the color value.

:root {
  --background-color: blue;
}

.box {
  background-color: var(--background-color);
}

In the above example however, there is nothing to stop someone using some other value for this property, perhaps setting it to a length. Having done so, anywhere that the property is used would have no background color as background-color: 12px is not valid. When browsers come across CSS they don't recognize as valid they throw that line away.

Using @property however, we can declare the custom property with a syntax of <color>. This shows that we need this property to have a value which is a valid color.

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

A feature of Houdini is the Worklet. A worklet is a module, written in JavaScript, that extends CSS using one of the Houdini APIs. You can see an example worklet on the PaintWorkletGlobalScope.registerPaint() page. Once a worklet has been registered you can use it in CSS just like any other value. This means that even if you are not a JavaScript developer, you can access Houdini APIs by using worklets other people have created.

The Houdini.how website has a number of worklets that you can try on your own site.

The @property at-rule allows you to register an advanced custom property.

• @property
• inherits
• initial-value
• syntax

• CSS Properties and Values API
• CSS Typed Object Model API
• CSS Painting API
• Worklet reference

• Properties and Values API Guide
• Typed OM API Guide
• Using the CSS Painting API

• Interactive introduction to Houdini
• A Practical Overview of CSS Houdini
• Smarter custom properties with Houdini's new API