CSS Variables
Use CSS custom properties (variables) for themes, reuse, and dynamic styling.
What you'll learn
- What CSS custom properties are and how to declare them
- Using variables for colors, spacing, and design tokens
- How the cascade and inheritance apply to custom properties
- Changing variables with JavaScript for dynamic themes
Concept
CSS Variables
CSS Custom Properties (commonly called CSS variables) let you store values in a named reference and reuse them throughout your stylesheet. Declare one with a double dash, reference it with var():
:root {
--primary: #2563eb;
--spacing: 16px;
}
.button {
background: var(--primary);
padding: var(--spacing);
}
Change the variable in one place, and every reference updates. This makes themes, spacing systems, and consistent design far easier to maintain.
Why Not Preprocessor Variables?
Sass and Less have variables too, but CSS variables have a superpower: they are live in the browser. They follow the cascade and can be overridden at any element, not just at compile time. You can change them with media queries (responsive themes), with JavaScript (dark mode toggle), and they inherit through the DOM tree. Preprocessor variables are static — once compiled, they are gone. CSS variables are dynamic.
Design Tokens
Variables are the foundation of a design token system. Define your brand colors, spacing scale, font sizes, border radii, and shadows as variables on :root, then use only those variables in your components. This ensures consistency (every button uses the same primary color) and makes rebranding a one-line change. A well-structured token system is the difference between a maintainable and an unmaintainable stylesheet.
Theming with Variables
Dark mode becomes trivial with variables. Define light values on :root and dark values under a [data-theme="dark"] selector:
:root { --bg: #ffffff; --text: #1f2937; }
[data-theme="dark"] { --bg: #1f2937; --text: #ffffff; }
body { background: var(--bg); color: var(--text); }
Toggle the data-theme attribute with JavaScript, and the entire page re-themes instantly — no reload, no duplication.
Fallback Values
var() accepts a fallback: var(--primary, #2563eb). If the variable is not defined, the fallback is used. This is useful for optional customization and for safety when a variable might not be set in a particular context.
Example
/* Design tokens defined on :root */
:root {
--color-primary: #2563eb;
--color-bg: #ffffff;
--color-text: #1f2937;
--radius: 8px;
--space: 16px;
}
/* Dark theme overrides */
[data-theme="dark"] {
--color-bg: #0f172a;
--color-text: #e2e8f0;
}
/* Components use only variables, never raw values */
.card {
background: var(--color-bg);
color: var(--color-text);
border-radius: var(--radius);
padding: var(--space);
border: 1px solid var(--color-primary);
}
/* Responsive spacing with a media query override */
@media (min-width: 768px) {
:root { --space: 24px; }
}
Design tokens are defined once on :root. The dark theme overrides only the variables that change. Components reference variables exclusively, so changing a token updates every component. The media query increases spacing on larger screens by overriding one variable.
Try it
- Image Color Picker
Pick exact hex values to use as your CSS color variables.
- SVG Optimizer
SVGs can reference CSS variables for theming — optimize and inspect.
Common mistakes
The mistake
Defining variables on a specific element instead of :root, limiting their scope.
The fix
Define global design tokens on :root so they are available everywhere. Define component-specific variables on the component itself. Use :root for shared values and scope for local overrides.
The mistake
Using var() without a fallback for critical values, risking unstyled content.
The fix
Provide a fallback in var(--name, fallback) for important properties. If a variable fails to load (e.g., a stylesheet did not load), the fallback ensures the element is still styled, not broken.
Related Resources
Related Cheatsheets
- CSS Cheatsheet
Reference for custom properties, var(), and theming patterns.
Practice CSS Variables
2 exercises
Look up unfamiliar terms
A beginner-friendly glossary explains jargon in plain English — variables, functions, DOM, Promise, and more.
Build real projects
Apply what you learned by building guided projects with starter code and solutions.
Decode error messages
Plain-English explanations of common errors — what they mean, why they happen, and how to fix them.