Skip to content
Velloreth
Web Development 7 min read

CSS Custom Properties: Variables That Actually Work

Custom properties are live CSS variables with inheritance and cascade. Learn the syntax, theming patterns, and how they differ from preprocessor variables.

By

The syntax

Declare with a double dash, read with var().

:root {
  --color-primary: #2563eb;
  --spacing-unit: 0.5rem;
  --radius: 8px;
}

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

The declaration is a normal CSS declaration, so it participates in the cascade and inherits.

Why they are different from preprocessor variables

Sass and Less variables are replaced at build time. Custom properties are resolved by the browser at runtime.

// Sass: replaced at build time
$primary: #2563eb;
.button { color: $primary; }
// compiles to: .button { color: #2563eb; }
/* Custom property: resolved at runtime */
:root { --primary: #2563eb; }
.button { color: var(--primary); }
/* stays as var(--primary) in the output */

The consequences:

Sass variableCustom property
ResolvedBuild timeRuntime
Can change at runtimeNoYes
InheritsNoYes
Works in media queriesNoYes
Readable by JavaScriptNoYes
Can hold partial valuesNoYes

The runtime resolution is what makes theming possible.

Inheritance and the cascade

Custom properties inherit, which is what makes scoped overrides work.

:root {
  --text-color: #111;
}

.card {
  --text-color: #444; /* overrides for this subtree */
}

.card p {
  color: var(--text-color); /* #444 inside a card */
}

Every descendant of .card sees the overridden value. This is how component-level theming works without repeating declarations.

Theming

The killer use case. Define tokens once, override them per theme.

:root {
  --bg: #ffffff;
  --text: #111827;
  --border: #e5e7eb;
  --accent: #2563eb;
}

@media (prefers-color-scheme: dark) {
  :root {
    --bg: #0f172a;
    --text: #f1f5f9;
    --border: #1e293b;
    --accent: #60a5fa;
  }
}

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

.card {
  border: 1px solid var(--border);
}

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

Every component that uses var() updates automatically. No component needs to know about dark mode.

For a manual toggle, use a class instead of the media query:

.dark {
  --bg: #0f172a;
  --text: #f1f5f9;
}
document.documentElement.classList.toggle('dark');

The toggle is one line, because the theme is entirely in the tokens.

Partial values

Custom properties can hold part of a value, which enables composition.

:root {
  --brand-rgb: 37 99 235;
}

.button {
  background: rgb(var(--brand-rgb));
}

.button:hover {
  background: rgb(var(--brand-rgb) / 0.85); /* same colour, different alpha */
}

.overlay {
  background: rgb(var(--brand-rgb) / 0.1);
}

The colour is defined once, and the alpha varies per use. This is not possible with a preprocessor variable holding a complete colour.

Fallbacks

.button {
  color: var(--button-color, #2563eb); /* fallback if undefined */
}

The fallback can be another var():

color: var(--component-color, var(--global-color, black));

A fallback is worth adding when the property might not be defined — for example, in a component used outside its usual context.

Scoped component tokens

A common pattern: define a component’s tokens with defaults, and let the consumer override them.

.button {
  --button-bg: var(--accent);
  --button-fg: white;
  --button-padding: 0.5rem 1rem;

  background: var(--button-bg);
  color: var(--button-fg);
  padding: var(--button-padding);
}

.button--danger {
  --button-bg: #dc2626;
}

The component declares its own API through custom properties. A variant overrides one token, and the component’s rules do not change.

This is how design systems expose theming without a proliferation of modifier classes.

Responsive tokens

Custom properties can change in media queries, which makes responsive spacing clean.

:root {
  --space: 1rem;
  --container: 100%;
}

@media (min-width: 768px) {
  :root {
    --space: 1.5rem;
    --container: 720px;
  }
}

@media (min-width: 1200px) {
  :root {
    --space: 2rem;
    --container: 1140px;
  }
}

.section {
  padding: var(--space);
  max-width: var(--container);
  margin-inline: auto;
}

The component uses one token, and the token changes at breakpoints. No component-level media queries.

@property

By default, custom properties are untyped strings, so the browser cannot animate them. @property gives them a type.

@property --angle {
  syntax: '<angle>';
  initial-value: 0deg;
  inherits: false;
}

.spinner {
  animation: spin 1s linear infinite;
}

@keyframes spin {
  to { --angle: 360deg; }
}

With the type declared, the property interpolates smoothly. Without it, the value jumps.

@property also lets you set an initial value and control inheritance, which makes custom properties behave more like real CSS properties.

Gotchas

Custom properties are not validated until used. A typo in a value is not caught at declaration time; it fails when the property is used, and the declaration is ignored.

:root {
  --size: 10p; /* invalid, but not reported here */
}

.box {
  width: var(--size); /* ignored — width falls back to auto */
}

Whitespace matters in partial values. --rgb: 37, 99, 235 with commas does not work in rgb(var(--rgb) / 0.5). Use space-separated channels.

They inherit, which can surprise. A custom property set on a parent affects all descendants. That is usually the point, but it can leak.

They cannot be used in media query conditions. @media (min-width: var(--bp)) does not work, because media queries are evaluated before custom properties resolve.

They are not available in @import URLs or in selectors.

Reading and writing from JavaScript

Custom properties are readable and writable at runtime, which makes them a clean bridge between CSS and JavaScript.

// Read a computed value
const styles = getComputedStyle(document.documentElement);
const accent = styles.getPropertyValue('--accent').trim();

// Write a value
document.documentElement.style.setProperty('--accent', '#dc2626');

The read returns the resolved value as a string, including any whitespace, which is why .trim() is usually needed.

The pattern that works best: JavaScript sets a token, and CSS decides how to use it. This keeps styling in the stylesheet and logic in the script.

// JavaScript supplies the data
element.style.setProperty('--progress', `${percent}%`);
/* CSS decides the presentation */
.progress-bar::after {
  width: var(--progress, 0%);
  transition: width 0.3s ease;
}

The alternative — setting element.style.width directly — puts presentation in the script and makes the styling harder to find and change.

Custom properties in design systems

A design system usually has two tiers of tokens, and custom properties express both.

Primitive tokens are the raw values.

:root {
  --blue-500: #3b82f6;
  --blue-600: #2563eb;
  --gray-100: #f3f4f6;
  --gray-900: #111827;
}

Semantic tokens map primitives to meaning.

:root {
  --color-bg: var(--gray-100);
  --color-text: var(--gray-900);
  --color-action: var(--blue-600);
  --color-action-hover: var(--blue-500);
}

Components use the semantic tokens, never the primitives.

.button {
  background: var(--color-action);
  color: var(--color-bg);
}

.button:hover {
  background: var(--color-action-hover);
}

The benefit is that a theme change touches only the semantic layer. Switching to a dark palette means redefining --color-bg and --color-text, and every component follows. If components referenced --gray-100 directly, the theme change would require editing each one.

Practical guidance

  • Define design tokens on :root and use them everywhere.
  • Override tokens for themes rather than writing theme-specific rules.
  • Use partial values for colour composition.
  • Provide fallbacks for tokens that might be undefined.
  • Expose component tokens as a theming API.
  • Change tokens in media queries for responsive spacing.
  • Use @property when you need to animate a custom property.
  • Remember they are not validated until used — check the Computed tab when a value is ignored.

For the related guides, see css-specificity-explained and css-pseudo-classes-guide. For the broader context, css-grid-complete-guide and responsive-design-breakpoints.

Quotable summary

Custom properties are declared with a double dash and read with var(), and unlike preprocessor variables they are resolved by the browser at runtime, so they can change with a media query, a class, or JavaScript. They inherit and participate in the cascade, which is what makes scoped overrides and component-level theming work. They can hold partial values, so a colour channel list can be composed with different alphas. Theming is the killer use case: define tokens on :root and override them in a dark-mode block, and every component using var() updates automatically. Always provide a fallback for values that might be undefined, and remember that custom properties are not validated until they are used, so a typo fails silently at the point of use.

Frequently asked questions

What is a CSS custom property?
A custom property is a variable declared in CSS with a double-dash prefix, such as --color-primary, and read with var(--color-primary). It is resolved by the browser at runtime and participates in the cascade.
What is the difference between a custom property and a Sass variable?
A Sass variable is replaced at build time and cannot change at runtime. A custom property is resolved by the browser, so it can be changed by a media query, a class, or JavaScript, and it inherits.
How do I implement dark mode with custom properties?
Define your colour tokens on :root, then override them inside a media query for prefers-color-scheme or a class like .dark. Every component that uses var() updates automatically.
Can custom properties hold partial values?
Yes. You can store a colour channel list like 255 0 0 and use it as rgb(var(--red) / 0.5), which lets you vary the alpha without redefining the colour.
What is the fallback syntax for var()?
var(--name, fallback) uses the fallback if --name is not defined. The fallback can be any value, including another var().
Are custom properties animatable?
They are not animatable by default, because the browser does not know their type. Registering them with @property gives them a type, which makes them animatable and interpolatable.