HTML and CSS Custom Properties (CSS Variables)
HTML & CSS: Custom Properties (CSS Variables)
CSS custom properties, commonly called variables, let you centralize design tokens like colors, spacing, and typography.
They enable dynamic theming and reduce duplication across components.
Declaring variables
- Use the
:rootselector to define global tokens. - Variables are written as
--token-nameand accessed withvar(--token-name). - Custom properties inherit, so redefine them on containers to theme subsections.
Note: :root targets the whole document, so variables defined there are available everywhere.
If you want to read more about CSS Custom Properties or get an in-depth understanding, go to CSS Custom Properties in our CSS tutorial.
Example: Design Tokens
Token setup
:root {
--color-brand: #2563eb;
--color-brand-contrast: #eef2ff;
--font-base: "Inter", system-ui, sans-serif;
--space-md: clamp(1rem, 2vw, 1.625rem);
}
main {
font-family: var(--font-base);
padding: var(--space-md);
background: var(--color-brand-contrast);
}
.btn-primary {
background: var(--color-brand);
color: #fff;
padding: 0.75rem 1.5rem;
border-radius: 999px;
}
Changing a token once updates every place it is used with var(--token), making themes and global tweaks easy.
Dynamic theming
- Switch themes by toggling class names on
<html>or<body>. - Media queries can update variables for prefers-color-scheme.
- JavaScript can read and update custom properties at runtime.
Note: Because variables are live, changing them once automatically updates every place they are used.
Light/dark toggle
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="styles.css" type="text/css">
<script>
const toggleTheme = () => {
const root = document.documentElement;
const next = root.dataset.theme === "dark" ? "light" : "dark";
root.dataset.theme = next;
};
</script>
</head>
<body>
<button onclick="toggleTheme()">Toggle theme</button>
</body>
</html>
:root {
color-scheme: light dark;
--surface: #ffffff;
--text: #0f172a;
}
:root[data-theme="dark"] {
--surface: #0f172a;
--text: #e2e8f0;
}
body {
margin: 0;
background: var(--surface);
color: var(--text);
font-family: "Inter", sans-serif;
transition: background 0.3s ease, color 0.3s ease;
}
Scoping tokens
- Create component-specific tokens under a wrapper class to avoid global overrides.
- Use fallback values with
var(--token, fallback)to guard against missing definitions. - Combine with
@layeror style modules for maintainable design systems.
Note: Fallbacks act like default values; they are used if the variable has not been set.
Runtime calculations
Variables work inside calc(), clamp(), gradients, and even media queries (where supported).
padding: calc(var(--space-md) * 1.5);background: linear-gradient(var(--angle, 45deg), ...);- Feature detect with
@supports (--custom: property).
