CSS Custom Properties Guide | CSS-Tricks

Everything important and useful to know about CSS Custom Properties. Like that they are often referred to as “CSS Variables” but that’s not their real name.
Advertise your product or service right here with the best front-end community on earth.
A custom property is most commonly thought of as a variable in CSS.
Above, --spacing is the custom property with 1.2rem as the value and var(--spacing) is the variable in use.
Perhaps the most valuable reason to use them: not repeating yourself (DRY code). In the example above, I can change the value 1.2rem in one place and have it affect two things. This brings something programming languages do to CSS.
There is a good bit to know about custom properties, so let’s get into it.
Custom properties must be within a selector and start with two dashes (--):
Best to stick with letters, numbers, and dashes while making sure the custom property is defined inside of a valid selector.
You can set the value of a custom property with another custom property:
Some people like doing it this way because it allows the name of a custom property to be descriptive and then used in another property with a more functional name, again helping keep things DRY. It can even help make the functional names more readable and understandable.
There is a big gotcha with custom properties that use other custom properties you should be aware of.
Custom properties are surprisingly tolerant when it comes to the values they accept.
Here are some basic examples that you’d expect to work, and do.
See that? They can be hex values, color functions, units of all kinds, and even strings of text.
But custom properties don’t have to be complete values like that. Let’s look at how useful it can be to break up valid CSS values into parts we can shove into custom properties.
You can use custom properties to break up multi-part values.
Let’s imagine you’re using a color function, say rgba(). Each color channel value in there can be its own custom property. That opens up a ton of possibilities, like changing the alpha value for a specific use case, or perhaps creating color themes.
Take HSL color, for example. We can split it up into parts, then very easily adjust the parts where we want. Maybe we’re working with the background color of a button. We can update specific parts of its HSL makeup when the button is hovered, in focus, or disabled, without declaring background on any of those states at all.
By breaking apart values like that, we can control parts of them in a way we never could before. Just look at how we didn’t need to declare all of the HSL arguments to style the hover, focus and disabled state of a button. We simply overrode specific HSL values when we needed to. Pretty cool stuff!
box-shadow doesn’t have a shorthand property for controlling the shadow’s spread on its own. But we could break out the box-shadow spread value and control it as a custom property (demo).
There is no such thing as a background-gradient-angle (or the like) shorthand for gradients. With custom properties, we can change just change that part as if there was such a thing.
Any property that supports multiple comma-separated values might be a good candidate for splitting values too, since there is no such thing as targeting just one value of a comma-separated list and changing it alone.
Say you wanted to remove just one of many multiple backgrounds at a media query. You could do that with custom properties like this, making it a trivial task to swap or override backgrounds.
We’re on a roll here, so we might as well do a few more examples. Like, hey, we can take the grid-template-columns property and abstract its values into custom properties to make a super flexible grid system:
CSS will soon get individual transforms but we can get it sooner with custom properties. The idea is to apply all the transforms an element might get up front, then control them individually as needed:
There are times when combining parts of values doesn’t work quite how you might hope. For example, you can’t make 24px by smashing 24 and px together. It can be done though, by multiplying the raw number by a number value with a unit.
The fact that custom properties use the cascade is one of the most useful things about them.
You’ve already seen it in action in many of the examples we’ve covered, but let’s put a point on it. Say we have a custom property set pretty “high up” (on the body), and then set again on a specific class. We use it on a specific component.
Then say we’ve got practical HTML like this:
The “module” in the sidebar has a gray background because custom properties (like many other CSS properties) inherit through the HTML structure. Each module takes the --background value from the nearest “ancestor” where it’s been defined in CSS.
So, we have one CSS declaration but it’s doing different things in different contexts, thanks to the cascade. That’s just cool.
This plays out in other ways:
Media queries don’t change specificity, but they often come later (or lower) in the CSS file than where the original selector sets a value, which also means a custom property will be overridden inside the media query:
Media queries aren’t only for screen sizes. They can be used for things like accessibility preferences. For example, dark mode:
You’ll often see custom properties being set “at the root.” Here’s what that means:
There is no particularly compelling reason to define custom properties like that. It’s just a way of setting custom properties as high up as they can go. If you like that, that’s totally fine. I find it somehow more normal-feeling to apply them to the html or body selectors when setting properties I intend to make available globally, or everywhere.
There is also no reason you need to set variables at this broad of a scope. It can be just as useful, and perhaps more readable and understandable, to set them right at the level you are going to use them (or fairly close in the DOM tree).
Note that setting a custom prope