A Complete Guide to Custom Properties

• Why care about CSS Custom Properties?
• A custom property is most commonly thought of as a variable in CSS.
• Naming custom properties
• Properties as properties
• Read also:
• Breaking up values
• Splitting colors
• Using the cascade
• Table

Why care about CSS Custom Properties?

1. They help DRY up your CSS. That is “Don’t Repeat Yourself.” Custom properties can make code easier to maintain because you can update one value and have it reflected in multiple places. Careful though, overdoing abstraction can make have the opposite effect and make code less understandable.
2. They are particularly helpful for things like creating color themes on a website.
3. They unlock interesting possibilities in CSS. In no small part because they cascade.
4. The fact that they can be updated in JavaScript opens up even more interesting possibilities.

A custom property is most commonly thought of as a variable in CSS.

.card {
    --spacing     : 1.2rem;
    padding       : var(--spacing);
    margin-bottom : var(--spacing);
}

Above,--spacing is the custom property with 1.2re mas the value and var(--spacing)

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.

Naming custom properties

Properties as properties

You can set the value of a custom property with another custom property:

html {
  --red: #a24e34;
  --green: #01f3e6;
  --yellow: #f0e765;

  --error: var(--red);
  --errorBorder: 1px dashed var(--red);
  --ok: var(--green);
  --warning: var(--yellow);
}

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.

Read also:

Breaking up values

Let’s imagine you’re using a color function, say rgba(). Each color chanel 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.

Splitting colors

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 background on any of those states at all.

Using the cascade

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.

This plays out in other ways:

button {
  --foo: Default;
}
button:hover {
  --foo: I win, when hovered;
  /* This is a more specific selector, so re-setting
     custom properties here will override those in `button` */
}

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.

Table

col1	col2	col3
value 1	value 2	value 3
value 1.1	value 2.1	value 3.1
total 1	total 2	total 3

For the second module, .sidebar is a closer ancestor than body, thus --background resolves to gray there, but white in other places.