CSS Custom Properties (Variables)

CSS custom properties, commonly called CSS variables, let you define a reusable value once and reference it throughout a stylesheet, and even update it dynamically at runtime with JavaScript or media queries. Before custom properties existed, CSS had no native concept of a variable, forcing teams to rely on preprocessors like Sass purely for that feature.

A custom property is declared with a name prefixed by two dashes (e.g. --primary-color) and is read anywhere with the var() function. Because custom properties participate in the cascade and inheritance like any other CSS property, they can be scoped globally on :root or overridden locally within any selector.

Why it matters

A brand colour used in fifty places should be defined once. CSS custom properties make that possible without a build tool, and because they are live in the browser they can be changed at runtime, which is how most dark-mode switches work. Design systems are built on them.

Declaring and Using Custom Properties

Custom properties are typically declared on :root (a pseudo-class matching the <html> element) so they're available globally: :root { --primary-color: #0057d9; }. They're consumed anywhere with var(--primary-color), and var() accepts an optional second argument as a fallback value if the variable is undefined: var(--gap, 1rem).

Scoping and Overriding

Because custom properties inherit and follow the cascade, redeclaring a variable inside a more specific selector overrides it only within that selector's scope, without affecting the global value. This makes them ideal for theming — a .dark-theme class can redefine --background-color and --text-color, and every component using var() for those values updates automatically wherever that class is applied.

Custom Properties vs. Preprocessor Variables

Sass or Less variables are resolved once at compile time and produce static CSS — they cannot change based on runtime conditions. CSS custom properties are live: they can be read and changed by JavaScript (element.style.setProperty('--x', 'value')), and they respond to media queries and pseudo-class state changes, making them strictly more powerful for dynamic theming, even though they don't include preprocessor features like mixins or nesting.

Examples

:root {
  --primary-color: #0057d9;
  --spacing-unit: 1rem;
  --border-radius: 8px;
}

.button {
  background: var(--primary-color);
  padding: var(--spacing-unit);
  border-radius: var(--border-radius);
}

.card {
  border: 1px solid var(--primary-color);
  padding: calc(var(--spacing-unit) * 2);
}

Both the button and the card pull their color, spacing, and radius from the same shared variables, so changing --primary-color in one place updates every consumer at once.

:root {
  --bg-color: #ffffff;
  --text-color: #111111;
}

.dark-theme {
  --bg-color: #111111;
  --text-color: #f5f5f5;
}

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

Applying the .dark-theme class to a container (or the body) flips the background and text colors for everything inside it, since the redefined variables cascade down without touching the :root defaults elsewhere.

Exercise

Define two custom properties on the root: a brand colour of #0f766e and a spacing value of 1rem. Use the brand colour for the heading text and the button background, and the spacing value for the padding of main. Give the button white text.

Expected result: a teal heading, a teal button with white text, and padding around the content.

/* The page contains: <main> with an <h1>, a <p> and a <button> */

:root {
  /* TODO: --brand and --space */
}

/* TODO: use the variables on h1, button and main */

/* The page contains: <main> with an <h1>, a <p> and a <button> */

:root {
  --brand: #0f766e;
  --space: 1rem;
}

h1 {
  color: var(--brand);
}

button {
  background: var(--brand);
  color: white;
}

main {
  padding: var(--space);
}

Quick quiz

Interview questions