CSS custom properties explained for new web developers

A lot of times, when writing code in your style sheet, you have to repeat the same value in several different CSS rules.

For example, in the following code base, we use the property border-radius in five different rules. Since we want to achieve a consistent design, we apply the same value (4px) to all these rules.

Example of a style sheet code-base presenting five different elements having the same border-radius value. — Here, changing border-radius from 4px to 8px requires to rewrite each value manually.

But what if the specs change for whatever reason?

In such a case, we must find and edit all these values one by one.

Thankfully, there is a better way.

We can use CSS custom properties.

Example of using a custom property for defining border radius. — Here, by using a custom property, we can just change the value of that property in the root level and it will automatically change to all five elements.

Now, you can just change the custom property, and the change will apply to all rules.

No need to go through CSS files.

NOTE: In a real project, each component would usually keep its own CSS rule, but all would use var(--corner-radius).

What are CSS custom properties, and how do they work?

CSS custom properties, also known as CSS variables, let you set a value and then apply that value multiple times in your CSS.

Code example of CSS properties defined globally.

The two dashes (--) at the start tell the browser that this is a custom property.

NOTE: The :root pseudo-class is often used to define global custom properties since it represents the highest-level parent in the DOM tree.

To read the value, use var():

Code example of applying custom properties with the use of var(). — To apply CSS custom properties we use the var() function.

Define custom properties locally

In our previous example, we defined the custom property in :root.

But you can define a custom property within a specific class if the value affects only certain, or even just one, components.

Code example of defining a custom property within a specific class. — In this example the –card-radius custom property could be only applied within the .card component(s).

Fallback values in custom properties

There are cases where a custom property might not be available.

For example, a component might expect an optional theme color.

In such cases, you can assign a fallback value to var().

Code example of applying a custom property with a fallback value. — Here, the #222 color is the fallback. If the –text-color custom property is not available, the function is going to use this value.

If --text-color property is never defined, the browser uses the fallback values after the commas.

Custom properties can also reference other custom properties

A custom property can use another custom property through var():

Code example showing a custom property getting its value from another one.

Here, --button-background gets its value from –brand-blue.

This is useful when you want meaningful names for the same value:

Code example of a custom property using another custom property through the var() function. — Here, –card-padding becomes 16px.

Custom properties are useful in creating theme-able designs

Custom properties are very useful for themes because you can change a few shared values and update the whole interface.

Let’s see an example:

Code example of how custom properties are very useful for dark themes. — In this example, When the page gets data-theme=”dark”, the same body and .card rules use the new values. You don’t need separate dark-mode styles for every component.

Although my blog doesn’t support comments, feel free to reply via email or X.