Skip to content
Tutorials Center
My learning

Topics

CSS Reference ยท Custom Properties, Cascade and Global Keywords

Custom properties (--*)

Reference for CSS custom properties: declaring --name values, reading them with var(), inheritance, fallbacks, scoping and common pitfalls.

A custom property is a property whose name you choose. Any name that starts with two hyphens, such as --brand or --gap-lg, is valid. You store a value in it once and read it anywhere with the var() function. People often call them CSS variables.

Unlike variables in a preprocessor, custom properties live in the browser. They take part in the cascade, they inherit, and JavaScript or media queries can change them while the page runs.

CSS
:root { --brand: #2a62d9; }
.button { background: var(--brand); }

Try it

Theme with variables
Scope and fallback

Syntax

CSS
--name: <declaration-value>;
property: var(--name, <fallback>);
  • Initial value: the guaranteed-invalid value (the property is simply "not set")
  • Applies to: all elements
  • Inherited: yes
  • Animatable: no by default (values swap abruptly); yes if registered with @property and given a syntax
  • Computed value: as specified, with any var() references replaced

Values

Value Description
Almost anything A color, length, number, string, list, a whole shorthand value or even a fragment like 10px solid. The browser stores the tokens and checks them where they are used.
Empty (--x:;) Valid, and different from not setting the property at all.
initial Resets to the guaranteed-invalid value.
var(--name) The value of the property on this element, if set and valid.
var(--name, fallback) Uses the fallback if the property is not set. The fallback can itself contain var().

Usage notes

  • Case-sensitive. --Brand and --brand are different properties.
  • Define high, override low. Put global values on :root and override them on a component or modifier class. Descendants inherit the change automatically.
  • Invalid at use time. If var() produces a value that is not valid for the property (such as --brand: 10px used as a background), the declaration becomes "invalid at computed-value time". The property then behaves as unset: inherited properties take the parent's value, others reset to their initial value. It does not fall back to an earlier declaration.
  • No variables in selectors or media queries. @media (min-width: var(--bp)) does not work, and a custom property cannot appear in a selector or property name.
  • Cycles. --a: var(--b); --b: var(--a) makes both invalid.
  • Units. Store 8 and write calc(var(--n) * 1px) when you need to do arithmetic, or store the full length 8px.
  • JavaScript. Change a value with element.style.setProperty('--brand', 'red') and read it with getComputedStyle(el).getPropertyValue('--brand').
  • Performance. Changing a custom property on a high ancestor makes the browser recompute styles for everything below it; scope frequently changing values to the smallest element.

Browser support

Supported in all current browsers. Registered custom properties (@property) are newer; check a compatibility table before relying on them.