How it works
The spec defines one property, --*: value <declaration-value>? (almost any tokens), initial value the guaranteed-invalid value, inherited, computed value "specified value with variables substituted". Each step explains a behaviour:
- Parse time. The declaration is kept as tokens; only unmatched closing brackets, top-level semicolons and a few bad tokens are rejected. A declaration that uses
var() is also kept without checking, since its final value is unknown.
- Cascade. Each
--* name is its own property, so the usual sort order decides which declaration wins on each element, !important included. The !important belongs to the custom property's own cascade; it is not carried into the value.
- Computed value of the custom property. Any
var() inside it is replaced now, on this element. The result is what children inherit.
- Computed value of the using property.
var() is replaced by the custom property's computed value, or by the fallback if that is guaranteed-invalid. Only now is the result parsed against the property's grammar. If it fails, the property computes as if it were unset.
Substitution is at the token level, not text: you can't build a single token, such as 20px, from two parts.
<style>
:root { --base: 8px; --space: calc(var(--base) * 2); }
.dense { --base: 4px; padding: var(--space); }
.fixed { --base: 4px; --space: calc(var(--base) * 2); padding: var(--space); }
.x { --gap: 20; margin-top: var(--gap)px; }
.y { --gap: 20; margin-top: calc(var(--gap) * 1px); }
</style>
<div class="dense">a</div><div class="fixed">b</div>
<p class="x">x</p><p class="y">y</p>
<script>
const style = (name) => getComputedStyle(document.querySelector(`.${name}`));
console.log(style("dense").paddingTop);
// → 16px
console.log(style("fixed").paddingTop);
// → 8px
console.log(style("x").marginTop);
// → 0px
console.log(style("y").marginTop);
// → 20px
</script>
.dense inherits --space already resolved at :root: its getPropertyValue("--space") returned calc(8px * 2). Redeclaring --space where --base changes, as .fixed does, recomputes it.
Edge cases
- Cycles.
--one: var(--two); --two: var(--one); on one element makes both guaranteed-invalid, so width: var(--one, 7px) used 7px. There's no way to read the parent's value of the same name: --x: var(--x) is a cycle of one, so with --x: 5px on the parent, the child's width: var(--x, 7px) was 7px.
- Empty values.
--a: ; is a valid empty value, and var(--a,) has a valid empty fallback.
- CSS-wide keywords. A custom property can't hold
initial as a value; --x: initial resets the custom property itself. A fallback can: color: var(--missing, initial) behaves as color: initial.
- Shorthands.
margin: var(--m, 4px) with --m: 1px 2px set inline computed to 1px 2px; one variable can fill several longhands.
- Whitespace. Leading and trailing whitespace is trimmed:
--x: red ; read back as "red" in both browsers.
Real-world scenario
A design system exposes tokens on :root and lets components override them:
:root { --radius: 8px; --surface: white; }
.button { border-radius: var(--radius); background: var(--surface); }
.toolbar { --radius: 4px; } /* every button inside gets 4px */
JavaScript can drive styles the same way: el.style.setProperty("--x", "9px") changed the computed margin of an element using var(--x) immediately, with no class juggling. For values derived from other tokens, declare the derivation where overrides happen (on the component, or on * when it must follow every element), not only on :root.
Trade-offs
- No types. Errors surface as
unset at computed-value time, far from the token that caused them. @property adds a syntax and a guaranteed initial value.
- Discrete animation until registered.
- Global reach. A token set on
:root is visible to every element; @property with inherits: false keeps one local.
- Values only. Not usable in selectors, property names, or media query conditions.