Recently I interviewed Stefan Judis for my upcoming book. We discussed CSS custom properties, and something interesting happened.

We had a period of a few minutes where we were talking past one another, because, as it turns out, we have completely opposite ideas about the use of CSS custom properties. I had never considered his approach, and I found it interesting enough to write this quick post.

Option 1

Take several site components, each with their own link and hover/focus colours. We want to use custom properties for those colours. Exactly how do we do that?

Before my discussion with Stefan that wasn’t even a question for me. I would do this:

.component1 {
	--linkcolor: red;
	--hovercolor: blue;
}

.component2 {
	--linkcolor: purple;
	--hovercolor: cyan;
}

a {
	color: var(--linkcolor);
}

a:hover,a:focus {
	color: var(--hovercolor)
}

I set the normal and hover/focus colour as a custom property, and leave the definition of those properties to the component the link appears in. The first and second component each define different colours, which are deployed in the correct syntax. Everything works and all’s well with the world.

As far as I can see now this is the default way of using CSS custom properties. I wasn’t even aware that another possibility existed.

Option 2

Stefan surprised me by doing almost the complete opposite. He uses only a single variable and changes its value where necessary:

.component1 {
	--componentcolor: red;
}

.component1 :is(a:hover,a:focus) {
	--componentcolor: blue;
}
	
.component2 {
	--componentcolor: purple;
}

.component2 :is(a:hover,a:focus) {
	--componentcolor: cyan;
}
	
a {
	color: var(--componentcolor)		
}

At first I was confused. Why would you do this? What’s the added value of the custom property? Couldn’t you just have entered the colour values in the component styles without using custom properties at all?

Well, yes, you could. But that’s not Stefan’s point.

The point

In practice, component definitions have way more styles than just colours. There’s a bunch of box-model properties, maybe a display, and possibly text styling instructions. In any case, a lot of lines of CSS.

If you use custom properties only for those CSS properties that will change you give future CSS developers a much better and quicker insight in how your component works. If the definition uses a custom property that means the property may change in some circumstances. If it uses a fixed definition you know it’s a constant.

Suppose you encounter this component definition in a codebase you just inherited:

.component {
	--color: red;
	--background: blue
	--layout: flex;
	--padding: 1em;
	--borderWidth: 0.3em;
	display: var(--layout);
	color: var(--color);
	background: var(--background);
	padding: var(--padding);
	border: var(--borderWidth) solid black;
	margin: 10px;
	border-radius: 2em;
	grid-template-columns: repeat(3,1fr);
	flex-wrap: wrap;
}

Now you essentially found a definition file. Not only do you see the component’s default styles, you also see what might change and what will not. For instance, because the margin and border-radius are hard-coded you know they are never changed. In the case of the border, only the width changes, not the style or the colour. Most other properties can change.

The use of display: var(--layout) is particularly revealing. Apparently something somewhere changes the component’s layout from grid to flexbox. Also, if it’s a grid it has three equal columns, while if it’s a flexbox it allows wrapping. This suggests that the flexbox layout is used on narrower screens, switching to a grid layout on wider screens.

Where does the flexbox change to a grid? As a newbie to this codebase you don’t know, but you can simply search for --layout: grid and you’ll find it, probably neatly tucked away in a media query somewhere. Maybe there is a basic layout as well, which uses neither flexbox nor grid? Search for --layout: block and you’ll know.

Thus, this way of using custom properties is excellently suited for making readable code bases that you can turn over to other CSS developers. They immediately know what changes and what doesn’t.

Teaching aid?

There’s another potential benefit as well: this way of using custom properties, which are essentially variables, aligns much more with JavaScript’s use of variables. You set an important variable at the start of your code, and change it later on if necessary. This is what you do in JavaScript all the time.

Picking an option

Which option should you pick? That’s partly a matter of personal preference. Since the second option is still fairly new to me, and I rarely work on large projects, I am still feeling my way around it. Right at this moment I prefer the first way because I’m used to it. But that might change, given some extra time.

Still, I think Stefan is on to something. I think that his option is very useful in large codebases that can be inherited by other developers. I think it deserves careful consideration.

You’re reading a failed article. I hoped to write about @property and how it is useful for extending CSS inheritance considerably in many different circumstances. Alas, I failed. @property turns out to be very useful for font sizes, but does not even approach the general applicability I hoped for.

Grandparent-inheriting

It all started when I commented on what I thought was an interesting but theoretical idea by Lea Verou: what if elements could inherit the font size of not their parent, but their grandparent? Something like this:

div.grandparent {
	/* font-size could be anything */
}

div.parent {
	font-size: 0.4em;
}

div.child {
	font-size: [inherit from grandparent in some sort of way];
	font-size: [yes, you could do 2.5em to restore the grandparent's font size];
	font-size: [but that's not inheriting, it's just reversing a calculation];
	font-size: [and it will not work if the parent's font size is also unknown];
}

Lea told me this wasn’t a vague idea, but something that can be done right now. I was quite surprised — and I assume many of my readers are as well — and asked for more information. So she wrote Inherit ancestor font-size, for fun and profit, where she explained how the new Houdini @property can be used to do this.

This was seriously cool. Also, I picked up a few interesting bits about how CSS custom properties and Houdini @property work. I decided to explain these tricky bits in simple terms — mostly because I know that by writing an explanation I myself will understand them better — and to suggest other possibilities for using Lea’s idea.

Alas, that last objective is where I failed. Lea’s idea can only be used for font sizes. That’s an important use case, but I had hoped for more. The reasons why it doesn’t work elsewhere are instructive, though.

Tokens and values

Let’s consider CSS custom properties. What if we store the grandparent’s font size in a custom property and use that in the child?

div.grandparent {
	/* font-size could be anything */
	--myFontSize: 1em;
}

div.parent {
	font-size: 0.4em;
}

div.child {
	font-size: var(--myFontSize);
	/* hey, that's the grandparent's font size, isn't it? */
}

This does not work. The child will have the same font size as the parent, and ignore the grandparent. In order to understand why we need to understand how custom properties work. What does this line of CSS do?

--myFontSize: 1em;

It sets a custom property that we can use later. Well duh.

Sure. But what value does this custom property have?

... errr ... 1em?

Nope. The answer is: none. That’s why the code example doesn’t work.

When they are defined, custom properties do not have a value or a type. All that you ordered the browsers to do is to store a token in the variable --myFontSize.

This took me a while to wrap my head around, so let’s go a bit deeper. What is a token? Let’s briefly switch to JavaScript to explain.

let myVar = 10;

What’s the value of myVar in this line? I do not mean: what value is stored in the variable myVar, but: what value does the character sequence myVar have in that line of code? And what type?

Well, none. Duh. It’s not a variable or value, it’s just a token that the JavaScript engine interprets as “allow me to access and change a specific variable” whenever you type it.

CSS custom properties also hold such tokens. They do not have any intrinsic meaning. Instead, they acquire meaning when they are interpreted by the CSS engine in a certain context, just as the myVar token is in the JavaScript example.

So the CSS custom property contains the token 1em without any value, without any type, without any meaning — as yet.

You can use pretty any bunch of characters in a custom property definition. Browsers make no assumptions about their validity or usefulness because they don’t yet know what you want to do with the token. So this, too, is a perfectly fine CSS custom property:

--myEgoTrip: ppk;

Browsers shrug, create the custom property, and store the indicated token. The fact that ppk is invalid in all CSS contexts is irrelevant: we haven’t tried to use it yet.

It’s when you actually use the custom property that values and types are assigned. So let’s use it:

background-color: var(--myEgoTrip);

Now the CSS parser takes the tokens we defined earlier and replaces the custom property with them:

background-color: ppk;

And only NOW the tokens are read and intrepreted. In this case that results in an error: ppk is not a valid value for background-color. So the CSS declaration as a whole is invalid and nothing happens — well, technically it gets the unset value, but the net result is the same. The custom property itself is still perfectly valid, though.

The same happens in our original code example:

div.grandparent {
	/* font-size could be anything */
	--myFontSize: 1em; /* just a token; no value, no meaning */
}

div.parent {
	font-size: 0.4em;
}

div.child {
	font-size: var(--myFontSize);
	/* becomes */
	font-size: 1em; 
	/* hey, this is valid CSS! */
	/* Right, you obviously want the font size to be the same as the parent's */
	/* Sure thing, here you go */
}

In div.child he tokens are read and interpreted by the CSS parser. This results in a declaration font-size: 1em;. This is perfectly valid CSS, and the browsers duly note that the font size of this element should be 1em.

font-size: 1em is relative. To what? Well, to the parent’s font size, of course. Duh. That’s how CSS font-size works.

So now the font size of the child becomes the same as its parent’s, and browsers will proudly display the child element’s text in the same font size as the parent element’s while ignoring the grandparent.

This is not what we wanted to achieve, though. We want the grandparent’s font size. Custom properties — by themselves — don’t do what we want. We have to find another solution.

@property

Lea’s article explains that other solution. We have to use the Houdini @property rule.

@property --myFontSize {
	syntax: "<length>";
	initial-value: 0;
	inherits: true;
}

div {
	border: 1px solid;
	padding: 1em;
}

div.grandparent {
	/* font-size could be anything */
	--myFontSize: 1em;
}

div.parent {
	font-size: 0.4em;
}

div.child {
	font-size: var(--myFontSize);
}

Now it works. Wut? Yep — though only in Chrome so far.

What black magic is this?

Adding the @property rule changes the custom property --myFontSize from a bunch of tokens without meaning to an actual value. Moreover, this value is calculated in the context it is defined in — the grandfather — so that the 1em value now means 100% of the font size of the grandfather. When we use it in the child it still has this value, and therefore the child gets the same font size as the grandfather, which is exactly what we want to achieve.

(The variable uses a value from the context it’s defined in, and not the context it’s executed in. If, like me, you have a grounding in basic JavaScript you may hear “closures!” in the back of your mind. While they are not the same, and you shouldn’t take this apparent equivalency too far, this notion still helped me understand. Maybe it’ll help you as well.)

Unfortunately I do not quite understand what I’m doing here, though I can assure you the code snippet works in Chrome — and will likely work in the other browsers once they support @property.

Misson completed — just don’t ask me how.

Syntax

You have to get the definition right. You need all three lines in the @property rule. See also the specification and the MDN page.

@property --myFontSize {
	syntax: "<length>";
	initial-value: 0;
	inherits: true;
}

The syntax property tells browsers what kind of property it is and makes parsing it easier. Here is the list of possible values for syntax, and in 99% of the cases one of these values is what you need.

You could also create your own syntax, e.g.

syntax: "ppk | <length>"

Now the ppk keyword and any sort of length is allowed as a value.

Note that percentages are not lengths — one of the many things I found out during the writing of this article. Still, they are so common that a special value for “length that may be a percentage or may be calculated using percentages” was created:

syntax: "<length-percentage>"

Finally, one special case you need to know about is this one:

syntax: "*"

MDN calls this a universal selector, but it isn’t, really. Instead, it means “I don’t know what syntax we’re going to use” and it tells browsers not to attempt to interpret the custom property. In our case that would be counterproductive: we definitely want the 1em to be interpreted. So our example doesn’t work with syntax: "*".

initial-value and inherits

An initial-value property is required for any syntax value that is not a *. Here that’s simple: just give it an initial value of 0 — or 16px, or any absolute value. The value doesn’t really matter since we’re going to overrule it anyway. Still, a relative value such as 1em is not allowed: browsers don’t know what the 1em would be relative to and reject it as an initial value.

Finally, inherits: true specifies that the custom property value can be inherited. We definitely want the computed 1em value to be inherited by the child — that’s the entire point of this experiment. So we carefully set this flag to true.

Other use cases

So far this article merely rehashed parts of Lea’s. Since I’m not in the habit of rehashing other people’s articles my original plan was to add at least one other use case. Alas, I failed, though Lea was kind enough to explain why each of my ideas fails.

Percentage of what?

Could we grandfather-inherit percentual margins and paddings? They are relative to the width of the parent of the element you define them on, and I was wondering if it might be useful to send the grandparent’s margin on to the child just like the font size. Something like this:

@property --myMargin {
	syntax: "<length-percentage>";
	initial-value: 0;
	inherits: true;
}

div.grandparent {
	--myMargin: 25%;
	margin-left: var(--myMargin);
}

div.parent {
	font-size: 0.4em;
}

div.child {
	margin-left: var(--myMargin);
	/* should now be 25% of the width of the grandfather's parent */
	/* but isn't */
}

Alas, this does not work. Browsers cannot resolve the 25% in the context of the grandparent, as they did with the 1em, because they don’t know what to do.

The most important trick for using percentages in CSS is to always ask yourself: “percentage of WHAT?”

That’s exactly what browsers do when they encounter this @property definition. 25% of what? The parent’s font size? Or the parent’s width? (This is the correct answer, but browsers have no way of knowing that.) Or maybe the width of the element itself, for use in background-position?

Since browsers cannot figure out what the percentage is relative to they do nothing: the custom property gets the initial value of 0 and the grandfather-inheritance fails.

Colours

Another idea I had was using this trick for the grandfather’s text colour. What if we store currentColor, which always has the value of the element’s text colour, and send it on to the grandchild? Something like this:

@property --myColor {
	syntax: "<color>";
	initial-value: black;
	inherits: true;
}

div.grandparent {
	/* color unknown */
	--myColor: currentColor;
}

div.parent {
	color: red;
}

div.child {
	color: var(--myColor);
	/* should now have the same color as the grandfather */
	/* but doesn't */
}

Alas, this does not work either. When the @property blocks are evaluated, and 1em is calculated, currentColor specifically is not touched because it is used as an initial (default) value for some inherited SVG and CSS properties such as fill. Unfortunately I do not fully understand what’s going on, but Tab says this behaviour is necessary, so it is.

Pity, but such is life. Especially when you’re working with new CSS functionalities.

Conclusion

So I tried to find more possbilities for using Lea’s trick, but failed. Relative units are fairly sparse, especially when you leave percentages out of the equation. em and related units such as rem are the only ones, as far as I can see.

So we’re left with a very useful trick for font sizes. You should use it when you need it (bearing in mind that right now it’s only supported in Chromium-based browsers), but extending it to other declarations is not possible at the moment.

Many thanks to Lea Verou and Tab Atkins for reviewing and correcting an earlier draft of this article.