Custom Properties

Custom properties define a new value type in CSS that allows for the use of variables through the var() function.

One of the most commonly cited reasons for using CSS preprocessors like Sass or Less is the ability to use variables in your style sheets, because nobody likes to scour through thousands of lines of CSS just to change a hex code or a margin value. Even with search and replace, odds are we may end up missing one or two declarations. Using variables allows us to make the change in one place and be assured that change will propagate throughout our code.

The thing about CSS preprocessors is that they need to be compiled into CSS before the browser can recognize your code. Since they have to be compiled, these “variables” are essentially static, they cannot be updated dynamically.

CSS custom properties allow us to have true dynamic variables, that can be modified at run-time. This implies that as their values change, the browser will repaint as required. In addition, they are native to CSS, removing the need for compilation. We can also make use of standard CSS behavior like inheritance and cascade, something we could not with preprocessor variables.

Custom property value syntax

With CSS custom properties, developers can assign arbitrary values to a property with a name of their choice. Officially, a custom property is any valid identifier that starts with two dashes, for example --quux. They are case-sensitive, which means --quux and --QUUX do not refer to the same value.

This is a simple example of how to define and use a CSS custom property that we define as --primary-color.

:root {
	--primary-color: #0099cc;
}

h1 {
	color: var(--primary-color);
}

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

Changing the value of --primary-color will change the value of the header and links as well.

Custom properties can be declared on any element in the document and are resolved as per normal inheritance and cascade rules. You can see that from the example below:

var() function notation

The var() function is what makes CSS variables work, as it is how the browser will substitute and insert the assigned value as the value of a property. The syntax looks like this:

var() = var( <custom-property-name> [, <declaration-value> ]? )

It cannot be used as a property name, selector or anything other than a property value. The following are examples of invalid uses of the var() function:

/* Variables cannot be used as property names */
.baz {
	--side: padding-left;
	var(--side): 1em;
}

/* Variables cannot be used as part of a property */
.qux {
	--gap: 0.5;
	margin-left: var(--gap)em;
}

As a variable, it can be used in place of any value in any CSS property of an element. The first argument supplied is the name of the custom property to be substituted, and the second argument is the fallback value, used if the custom property specified is invalid.

p {
	margin: var(--margin, 1em 2em);
}

One thing to note is that var() functions are substituted at computed-value time. This means that if the result of the var() function is invalid during substitution, the CSS declaration itself is invalid at computed-value time.

Another gotcha was pointed out by Lea Verou in her talk at CSSConf. The url() function is the only function where CSS variables do not work properly due to its odd parsing behavior.

/* This does NOT work */
.element {
	--img: "sad";
	background: url("img/" var(--img) ".jpg") center / cover;
}

/* But this does */
.element {
	--img: url("img/cat.jpg");
	background: var(--img) center / cover;
}