Custom properties

What you'll learn

How to declare CSS variables, use them with var(), give them defaults, and change them for a whole section of a page.

Why it matters

Without variables, a brand colour is copied into dozens of rules. Changing it means hunting through the file. With a variable you change it once, and you can build themes such as light and dark easily.

Explanation

A custom property (CSS variable) is a name starting with two dashes, defined like any property and used with var():

• :root is the top of the document, so variables defined there are available everywhere.
• var(--name, fallback) uses a fallback value if the variable is missing.
• Variables cascade: a variable set on a smaller element overrides the global one for that element and its children.
• Unlike variables in Sass, CSS variables are live in the browser. JavaScript can change them with element.style.setProperty("--brand", "tomato").

Example

Step-by-step walkthrough

1. :root defines --brand (blue) and --radius.
2. .btn reads them with var().
3. The first button is blue, using the global value.
4. .warm redefines --brand as tomato. Any .btn inside it reads the new value, so the second button is red. The CSS of .btn did not change at all.

Try it yourself

Add a --text: white variable and use it for the button's color. Then override it inside .warm.

CSS variablesHTML / CSS

Editable code<style> :root { --brand: royalblue; --radius: 10px; } .btn { background: var(--brand); color: white; border: none; padding: 10px 18px; border-radius: var(--radius); } .warm { --brand: tomato; } </style> <button class="btn">Default</button> <div class="warm"> <button class="btn">Inside .warm</button> </div>

Run ResetCopyCtrl+Enter to run

Common mistakes

• Forgetting the two dashes: --brand, not -brand.
• Defining on body but using outside it, or defining on a child but using on a parent.
• Using a variable in a media query condition. Variables cannot be used there.
• No fallback for values that might be missing.

Quick quiz

Summary

• Declare --name: value; and read it with var(--name).
• Define globals on :root, override locally to restyle sections.
• Variables are live, which makes themes and runtime changes simple.

Next: keyframe animations.

:root {
  --brand: royalblue;
  --space: 16px;
}
button {
  background: var(--brand);
  padding: var(--space);
}

<style>
  :root {
    --brand: royalblue;
    --radius: 10px;
  }
  .btn {
    background: var(--brand);
    color: white;
    border: none;
    padding: 10px 18px;
    border-radius: var(--radius);
  }
  .warm {
    --brand: tomato;
  }
</style>

<button class="btn">Default</button>
<div class="warm">
  <button class="btn">Inside .warm</button>
</div>