Skip to content
Kuza Ndoto Academy

CSS Variables (Custom Properties)

Beginner → IntermediateChapter 5 · Page 18 of 224 min readUpdated 15 Nov 2026

CSS custom properties, usually called CSS variables, let you store a value once, give it a name and reuse it everywhere. Change the value in one place and the whole site updates, which makes colour themes, dark mode and consistent spacing far easier to manage.

Declaring and using a variable

A custom property's name starts with two dashes. You declare it like any other property, inside a rule, and read it with the var() function.

:root {
  --brand: #15803d;
  --radius: 10px;
  --space: 1rem;
}

.btn {
  background-color: var(--brand);
  border-radius: var(--radius);
  padding: var(--space) calc(var(--space) * 2);
}

The :root selector matches the <html> element, the top of the document, so variables declared there are available everywhere. The button gets a green background, 10px rounded corners and padding of 1rem top and bottom and 2rem left and right. Names are case-sensitive: --brand and --Brand are different variables.

Fallback values

var() accepts a second argument, used when the variable isn't defined:

.notice {
  color: var(--notice-colour, #b45309);
}

If no --notice-colour exists in scope, the text is amber (#b45309).

Variables cascade and inherit

Unlike variables in preprocessors such as Sass, which are replaced with fixed values before the browser ever sees them, CSS custom properties are live. They follow the cascade and are inherited by child elements, so you can override them for one part of the page:

:root {
  --accent: #1e3a8a;      /* blue everywhere by default */
}

.promo {
  --accent: #dc2626;      /* red inside .promo only */
}

a,
button {
  color: var(--accent);
}

Links and buttons are blue across the site, but inside any element with class promo they turn red. Nothing else needs to change: the a and button rules just read whatever --accent is at that point in the page. This pattern is how design systems build component variants.

Common mistake

A variable holds a value, not a whole declaration, and it can't be used in a selector or media query condition. @media (min-width: var(--tablet)) does not work. Also, if a variable contains a value that's invalid for the property where it's used (say, --size: red used in width), the browser doesn't fall back to your earlier declaration; the property behaves as if it were unset.

Themes and dark mode

Custom properties make theming almost effortless. Define your colours as variables, then redefine them for dark mode:

:root {
  --bg: #ffffff;
  --text: #1f2937;
  --surface: #f1f5f9;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #0f172a;
    --text: #e2e8f0;
    --surface: #1e293b;
  }
}

body {
  background: var(--bg);
  color: var(--text);
}
.card {
  background: var(--surface);
}

Every rule that uses the variables switches automatically when the user's device is in dark mode. To let users choose with a toggle button, redefine the variables on an attribute instead, such as [data-theme="dark"] { … }, and have JavaScript set that attribute on <html>.

Changing variables with JavaScript

Because they're live, scripts can update them and every use changes instantly:

document.documentElement.style.setProperty("--accent", "#7c3aed");

That one line turns every element that uses --accent purple. See Changing Content & Styles for more on scripting styles.

A design-token toolkit

Professional teams keep all their "design tokens" (colours, spacing steps, font sizes, radii and shadows) as variables at the top of the stylesheet. It keeps the design consistent, and a rebrand becomes a ten-minute job.

:root {
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-3: 1rem;
  --space-4: 2rem;
  --text-sm: 0.875rem;
  --text-lg: 1.25rem;
  --shadow: 0 4px 12px rgb(0 0 0 / 12%);
}

Try it

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Custom properties</title>
  <style>
    :root {
      --accent: #1e3a8a;
      --bg: #f8fafc;
      --text: #1f2937;
      --radius: 10px;
    }
    body {
      font-family: system-ui, sans-serif;
      background: var(--bg);
      color: var(--text);
      margin: 1.5rem;
    }
    .card {
      border: 2px solid var(--accent);
      border-radius: var(--radius);
      padding: 1rem;
      margin-bottom: 1rem;
      max-width: 320px;
    }
    .card h2 { color: var(--accent); margin-top: 0; }
    .btn {
      background: var(--accent);
      color: white;
      border: none;
      border-radius: var(--radius);
      padding: 0.5rem 1rem;
    }
    .sale { --accent: #dc2626; }
    .eco  { --accent: #15803d; --radius: 999px; }
  </style>
</head>
<body>
  <div class="card"><h2>Standard</h2><button class="btn">Buy</button></div>
  <div class="card sale"><h2>On sale</h2><button class="btn">Buy</button></div>
  <div class="card eco"><h2>Eco range</h2><button class="btn">Buy</button></div>
</body>
</html>

Three cards appear, built from exactly the same rules. The first is dark blue (border, heading and button). The second is red, because .sale overrides --accent. The third is green, and its border and button are fully rounded pills because .eco also overrides --radius. Change --accent in :root and only the first card changes.

Key points

  • Declare with --name: value; and use with var(--name, fallback).
  • Variables on :root are global; redefining them on an element changes them for that element and its children.
  • They're live: media queries, classes and JavaScript can change them at run time.
  • Use them for design tokens and for light and dark themes.
Up next · Modern CSSModern CSS Featuresclamp(), :has(), nesting, container queries and more.
→

Tip: use the ← and → keys to move between pages.