Two options for using custom properties

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.

I'm writing a CSS book.

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.

Thus this option may be better suited to teaching CSS to JavaScripters, which remains one of my preoccupations due to the upcoming book.

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.

I'm writing a CSS book.

This is the blog of Peter-Paul Koch, web developer, consultant, and trainer. You can also follow him on Twitter or Mastodon.
Atom RSS

If you like this blog, why not donate a little bit of money to help me pay my bills?