var()

Inserts the value of a CSS variable, that is, a custom property written as --name. It also lets you provide a fallback value.

On this page

Example

#
CSS
:root {
  --brand: #7c3aed;
  --radius: 12px;
}

.alert {
  --tone: var(--brand);
  padding: 12px 14px;
  border-left: 4px solid var(--tone);
  border-radius: var(--radius);
  background: color-mix(in srgb, var(--tone) 15%, transparent);
}

.alert.error {
  --tone: #f43f5e;
}
Preview

The .error variant changes just one variable. The colour of the bar and the background recalculate by themselves, because both declarations use --tone.

Definition and usage

#

CSS variables (officially: custom properties) are declared like regular properties, except that the name starts with two hyphens: --brand-color: #7c3aed;. The var(--brand-color) function inserts that value in any declaration. Changing one variable changes every place that uses it, even live, for example when switching a theme.

Variables follow the cascade and inheritance like any property. Declared on :root they work across the whole page, and declared on an element only in it and its descendants. A component can therefore override a variable locally (.alert { --color: #f43f5e; }) without touching the rest of the page. Case matters: --Color and --color are two different variables.

The second argument is a fallback value: var(--gap, 16px) uses 16px if the variable doesn’t exist. Everything after the first comma is treated as a single value, so var(--font, Georgia, serif) is valid. The fallback can also be another var(), for example var(--accent, var(--brand-color)).

The browser doesn’t check a variable’s contents at declaration time. If you insert it where it doesn’t fit, for example --gap: red in padding, the declaration doesn’t fall back to an earlier rule but takes the initial or inherited value. A variable can only be used as a value, never as a property name or part of a selector.

Syntax

#
Syntax
--name: value;
property: var(--name, <fallback value>?);

Usage variants

#
  • var(--brand)

    colour from the parent

    A variable declared on the container reaches the button and the label, because it is inherited down the tree.
  • var(--cta, #0ea5e9)

    fallback value

    Nobody declared the --cta variable, so the button gets the fallback value given after the comma.
  • .tag { --brand: … }

    override in a component

    The label overrides the variable locally. The button still uses the parent’s value, because the change affects only the label and its descendants.
  • var(--accent, var(--brand))

    fallback from another variable

    --accent is missing, so the browser reaches for the second variable, --brand. This is how you build a chain: a specific colour first, and a general one when it is missing.
  • calc(var(--scale) * 1rem)

    a number turned into a length

    The variable holds just a number, and calc() turns it into a unit. The button and the label get text of size 1.4rem.
  • --brand: 20px

    invalid value

    The variable exists, but 20px is not a colour. The fallback value doesn’t kick in, because the variable isn’t empty: the button loses its background, and the label its border and colour.

Usage variants in practice

#

var(--brand)

A variable declared on the container reaches the button and the label, because it is inherited down the tree.
.demo { --brand: #7c3aed; }

var(--cta, #0ea5e9)

Nobody declared the --cta variable, so the button gets the fallback value given after the comma.
.btn { background: var(--cta, #0ea5e9); }

.tag { --brand: … }

The label overrides the variable locally. The button still uses the parent’s value, because the change affects only the label and its descendants.
.demo { --brand: #7c3aed; }
.tag { --brand: #f43f5e; }

var(--accent, var(--brand))

--accent is missing, so the browser reaches for the second variable, --brand. This is how you build a chain: a specific colour first, and a general one when it is missing.
.demo { --brand: #10b981; }
.btn {
  background: var(--accent, var(--brand));
}

calc(var(--scale) * 1rem)

The variable holds just a number, and calc() turns it into a unit. The button and the label get text of size 1.4rem.
.demo { --scale: 1.4; }
.btn,
.tag {
  font-size: calc(var(--scale) * 1rem);
}

--brand: 20px

The variable exists, but 20px is not a colour. The fallback value doesn’t kick in, because the variable isn’t empty: the button loses its background, and the label its border and colour.
.demo { --brand: 20px; }

More examples

#
Variables set from JavaScript
CSS
.spotlight {
  background:
    radial-gradient(circle at var(--x, 50%) var(--y, 50%), rgb(124 58 237 / 0.45), transparent 60%),
    #18181b;
}
Preview

The script sets only two variables, --x and --y, and CSS does the rest. Until you move the cursor, the fallback value applies: the centre of the card.

Browser support

#

Widely available

Works in all modern browsers, phones included. You can use it without worry.

  • Chrome
  • Edge
  • Firefox
  • Safari

Good practices

#
  • The fallback value applies only when the variable doesn’t exist. If it exists but has an invalid value, var() won’t reach for the fallback.
  • You can read and change variables from JavaScript: getComputedStyle(el).getPropertyValue("--brand") and el.style.setProperty("--brand", "#10b981").
  • A variable won’t glue a unit onto a number: var(--n)px doesn’t work. Use calc(var(--n) * 1px).

Related entries

#

Practise it in lessons

#

Spotted a mistake or missing an example? Write to us.