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.
:root { --brand: #2a62d9; } .button { background: var(--brand); }
Try it
Syntax
--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
@propertyand 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.
--Brandand--brandare different properties. - Define high, override low. Put global values on
:rootand 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: 10pxused as abackground), the declaration becomes "invalid at computed-value time". The property then behaves asunset: 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
8and writecalc(var(--n) * 1px)when you need to do arithmetic, or store the full length8px. - JavaScript. Change a value with
element.style.setProperty('--brand', 'red')and read it withgetComputedStyle(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.