CSS Foundations
CSS Variables
Define reusable values that participate in the cascade and can change across components, themes, and media conditions. The examples show global tokens, component-level overrides, fallbacks, inheritance, and typed properties registered with @property.
Custom properties are values stored in the CSS cascade. Unlike preprocessor variables, they remain available in the browser, inherit by default, and can change with selectors, media queries, themes, and component state.
A useful custom property names a decision rather than merely replacing a literal. Tokens such as --surface, --card-gap, or --button-bg reveal why a value exists and where it may vary. Local custom properties also create a clean component API: a modifier can change one token instead of repeating the component’s declarations. This topic also connects with Cascade & Inheritance and CSS Theming.
Variables that belong to CSS
A custom property starts with two hyphens and stores a token sequence. It follows the cascade and inherits by default, which makes it different from a text replacement performed by a preprocessor.
Example
css
:root {
--color-accent: #0f766e;
--space-card: 1.25rem;
}
.card {
padding: var(--space-card);
border-top: 0.25rem solid var(--card-accent, var(--color-accent));
}The second argument to var() is a fallback used when the referenced custom property is missing or invalid. A fallback is not used merely because the final value is unsupported.
Local tokens keep components flexible
Example
css
.button {
--button-bg: #334155;
--button-fg: white;
background: var(--button-bg);
color: var(--button-fg);
}
.button--danger { --button-bg: #b91c1c; }Typed custom properties
Example
css
@property --progress {
syntax: "<number>";
inherits: false;
initial-value: 0;
}@property can give a custom property a type, an initial value, and explicit inheritance behavior. Typed values can also animate in ways untyped custom properties cannot.
Custom Property Syntax
| Syntax | Purpose | Example |
|---|---|---|
| --name | Declares a custom property. | --space: 1rem |
| var() | Reads a custom property. | gap: var(--space) |
| var() fallback | Supplies a value when the property is invalid or missing. | color: var(--ink, black) |
| @property | Registers type, inheritance, and an initial value. | @property --angle { ... } |
Complete Example
Run the complete document below in the Try It editor. Resize the preview or interact with the controls where the example calls for it.
Complete runnable example
html
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>CSS Variables example</title>
<style>
* { box-sizing: border-box; }
body {
margin: 0;
padding: 2rem;
font-family: system-ui, sans-serif;
line-height: 1.5;
}
main { max-width: 70rem; margin-inline: auto; }
article, section, aside, form, .card, .panel {
padding: 1rem;
border: 1px solid #cbd5e1;
border-radius: 0.6rem;
}
:root {
--color-accent: #0f766e;
--space-card: 1.25rem;
}
.card {
padding: var(--space-card);
border-top: 0.25rem solid var(--card-accent, var(--color-accent));
}
.button {
--button-bg: #334155;
--button-fg: white;
background: var(--button-bg);
color: var(--button-fg);
}
.button--danger { --button-bg: #b91c1c; }
@property --progress {
syntax: "<number>";
inherits: false;
initial-value: 0;
}
</style>
</head>
<body>
<main><article class="card" style="--card-accent:#7c3aed"><h1>Local design tokens</h1><button class="button">Default</button> <button class="button button--danger">Danger</button></article></main>
</body>
</html>Browser Support
Feature | Chrome | Edge | Firefox | Safari |
|---|---|---|---|---|
| Custom properties | 49 | 15 | 31 | 9.1 |
Versions show the first stable desktop release with unprefixed support. Data source: MDN Browser Compatibility Data 8.0.8. A partial-support note is included where it changes how the example behaves.
Notes
- Test the example with real content, keyboard input, browser zoom, and the narrowest layout your project supports.
- Use a fallback when the support table shows that one of your required browsers predates the feature.
Conclusion
Custom properties work best as named design decisions that can change through the cascade.
Keep global tokens small and meaningful, then translate them into local component tokens where necessary. Add @property only when a value needs explicit syntax, controlled inheritance, or interpolation; ordinary custom properties remain the simpler choice for most design tokens.