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 Velloreth
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 variable | Custom property | |
|---|---|---|
| Resolved | Build time | Runtime |
| Can change at runtime | No | Yes |
| Inherits | No | Yes |
| Works in media queries | No | Yes |
| Readable by JavaScript | No | Yes |
| Can hold partial values | No | Yes |
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
:rootand 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
@propertywhen 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.