CSS Custom Properties

CSS custom properties (also called CSS variables) let you store a value once and reuse it throughout your stylesheet. When you change the value in one place, it updates everywhere. They are the foundation of design systems and theming in modern CSS.

Declaring custom properties

Custom property names start with --. Declare them on :root to make them available globally throughout the entire page.

:root {
  --color-primary: #3b82f6;
  --color-text: #1f2937;
  --color-background: #ffffff;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 32px;
  --font-size-base: 1rem;
  --border-radius: 6px;
}

Using var()

Reference a custom property anywhere in your CSS with var().

button {
  background-color: var(--color-primary);
  color: white;
  padding: var(--spacing-sm) var(--spacing-md);
  border-radius: var(--border-radius);
}

h1 {
  color: var(--color-text);
  margin-bottom: var(--spacing-lg);
}

If you need to change your primary colour across the entire site, you update one line in :root instead of finding every occurrence in your stylesheets.

Fallback values

var() accepts an optional fallback as the second argument. If the custom property is not defined, the fallback is used instead.

button {
  background-color: var(--color-primary, #3b82f6);
}

Scope

Custom properties cascade and inherit just like other CSS properties. If you declare a property on a specific element, it only applies to that element and its children. This lets you create local overrides without affecting the rest of the page.

.dark-section {
  --color-text: #f9fafb;
  --color-background: #111827;
}

Any element inside .dark-section that uses var(--color-text) or var(--color-background) will get the overridden values.

Theming with data attributes

A common pattern for dark mode and theme switching is to redefine custom properties under a data attribute selector.

:root {
  --color-background: #ffffff;
  --color-text: #1f2937;
  --color-surface: #f3f4f6;
}

[data-theme="dark"] {
  --color-background: #111827;
  --color-text: #f9fafb;
  --color-surface: #1f2937;
}

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

Toggle the theme in JavaScript by setting the attribute on the root element:

document.documentElement.setAttribute('data-theme', 'dark');
document.documentElement.setAttribute('data-theme', 'light');

Updating properties with JavaScript

Unlike preprocessor variables (such as Sass $variable), CSS custom properties are live. They exist in the browser at runtime and can be read and changed with JavaScript.

/* Set a property */
document.documentElement.style.setProperty('--color-primary', '#10b981');

/* Read a property */
const value = getComputedStyle(document.documentElement)
  .getPropertyValue('--color-primary');

This makes CSS custom properties useful for dynamic theming, user-controlled settings, and animation values that change based on scroll position or user input.