CSS custom properties, also known as CSS
let you define your own properties in CSS and use their values throughout your
CSS. While incredibly useful today, they have shortcomings that can make them
hard to work with: they can take any value so they may be accidentally
overridden with something unexpected, they always inherit their values from
their parent, and you can’t transition them. With Houdini’s CSS Properties and
Values API Level 1,
now available in Chrome 78, these shortcomings are transcended, making CSS
custom properties incredibly powerful!
What Is Houdini?
Before talking about the new API, let’s talk about Houdini quickly. The CSS-TAG
Houdini Task Force, better known as CSS Houdini or simply Houdini, exists to
“develop features that explain the ‘magic’ of styling and layout on the web”.
The collection of Houdini specifications are
designed to open up the power of the browser’s rendering engine, allowing both
deeper insight into our styles and the ability to extend our rendering engine.
without a performance hit are finally possible. Houdini has the potential to
superpower creativity on the web.
CSS Properties and Values API Level 1
The CSS Properties and Values API Level
1 (Houdini Props and
Vals) allows us to give structure to our custom properties. This is the current
situation when using custom properties:
Because custom properties don’t have types, they can be overridden in unexpected
ways. For example, consider what happens if you define
--my-color with a URL.
--my-color isn’t typed, it doesn’t know that a URL isn’t a valid
color value! When we use it, it falls back to default values (black for
background). With Houdini Props and Vals, custom properties can
be registered so that the browser knows what it should be!
Now, the custom property
--my-color is registered as a color! This tells the
browser what kinds of values are allowed and how it can type and treat that
Anatomy of a registered property
Registering a property looks like this:
It supports the following options:
The name of the custom property.
How to parse the custom property. You can find a complete list of possible values in the CSS Values and Units specification. Defaults to
Whether it inherits its parent’s value. Defaults to
Initial value of the custom property.
+signifies that it accepts a space-separated list of values of
that syntax. For example,
<length>+would be a space-separated list of
#signifies that it accepts a comma-separated list of values of
that syntax. For example,
<color>#would be a comma-separated list of
|between syntaxes or identifiers signifies that any of the provided
options are valid. For example,
<color># | <url> | magicwould allow either
a comma-separated list of colors, a URL, or the word
There are two gotchas with Houdini Props and Vals. The first is that, once
defined, there’s no way to update an existing registered property, and trying to
re-register a property will throw an error indicating that it’s already been
Second, unlike standard properties, registered properties aren’t validated when
they’re parsed. Rather they’re validated when they’re computed. That means both
that invalid values won’t appear as invalid when inspecting the element’s
properties, and including an invalid property after a valid one won’t fall back
to the valid one; an invalid property will, however, fall back to the registered
Animating custom properties
A registered custom property provides a fun bonus beyond type checking: the
ability to animate it! A basic animation example looks like this:
transition: --stop-color: 1s;
When you hover over the button, it’ll animate from red to green! Without
registering the property, it’ll jump from one color to the other Because,
without being registered, the browser doesn’t know what to expect between one
value and the next and therefore can’t guarantee the ability to transition them.
This example can be taken a step further, though, to animate CSS gradients! The
following CSS can be written with the same registered property:
background: linear-gradient(var(--stop-color), black);
transition: --stop-color 1s;
This will animate our custom property that’s part of the
animating our linear gradient. Check out the Glitch below to see the full code
in action and play around with it yourself.
Houdini is on its way to browsers, and with it,
entirely new ways of working with and extending CSS. With the Paint
API already shipped
and now Custom Props and Vals, our creative toolbox is expanding, allowing us to
define typed CSS properties and use them to create and animate new and exciting
designs. There’s more on the way, too, in the Houdini issue
queue where you can give
feedback and see what’s next for Houdini. Houdini exists to develop features
that explain the “magic” of styling and layout on the web, so get out there and
put those magical features to good use.