CSS Variables (Custom Properties): A Practical Guide

CSS variables, officially custom properties, let you store values like colors and spacing once and reuse them everywhere. Change one line and your whole design updates. They're also the cleanest way to build theming and dark mode. Here's how to use them well.

How to create a CSS variable

Declare a variable with two dashes, and read it with the var() function. Most people declare their variables on :root, the top of the document, so they're available everywhere.

:root {
  --accent: #38bdf8;
  --space: 1rem;
  --radius: 12px;
}

.button {
  background: var(--accent);
  padding: var(--space);
  border-radius: var(--radius);
}

Now the accent color lives in one place. Change --accent and every element using it updates instantly.

Fallback values

var() accepts a second argument, a fallback used if the variable isn't defined. Handy for components that might be used outside your theme.

color: var(--text-color, #333); /* uses #333 if --text-color is unset */

CSS variables vs Sass variables

If you've used Sass, you might wonder why CSS variables matter. The difference is huge: Sass variables are compiled away before the browser sees them, they're static. CSS variables are live in the browser, so they can change at runtime with JavaScript, media queries, or a class, which unlocks theming.

Building dark mode with CSS variables

This is where CSS variables shine. Define your colors as variables, then override them under a dark-mode selector or media query. Nothing else in your CSS changes.

:root {
  --bg: #ffffff;
  --text: #111827;
}
@media (prefers-color-scheme: dark) {
  :root {
    --bg: #0b0f1a;
    --text: #e5e7eb;
  }
}
body { background: var(--bg); color: var(--text); }

Scoping variables to components

Variables cascade like any CSS, so you can redefine one on a specific element to change just that subtree. Great for component variants without new class soup.

.card { --pad: 1rem; padding: var(--pad); }
.card.spacious { --pad: 2rem; } /* same rule, roomier variant */

Define design tokens (colors, spacing, radius) as CSS variables once, and your whole UI becomes themeable and consistent with almost no extra code.

The short version

Create CSS variables with --name on :root and read them with var(--name). Unlike Sass variables, they're live in the browser, so you can override them for dark mode, themes and component variants at runtime. Use them for your design tokens and your CSS gets shorter and more flexible.

This site's entire theme, colors, spacing, radii, is built on CSS variables, which is how dark styling and accents stay consistent everywhere.