var()
Inserts the value of a CSS variable, that is, a custom property written as --name. It also lets you provide a fallback value.
Example
#: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;
}<div style="display: grid; gap: 8px;">
<div class="alert">A new lesson is now available.</div>
<div class="alert error">Failed to save your progress.</div>
</div>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
#--name: value;
property: var(--name, <fallback value>?);Usage variants
#colour from the parent
A variable declared on the container reaches the button and the label, because it is inherited down the tree.fallback value
Nobody declared the--ctavariable, so the button gets the fallback value given after the comma.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.fallback from another variable
--accentis 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.a number turned into a length
The variable holds just a number, andcalc()turns it into a unit. The button and the label get text of size 1.4rem.invalid value
The variable exists, but20pxis 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)
.demo { --brand: #7c3aed; }var(--cta, #0ea5e9)
--cta variable, so the button gets the fallback value given after the comma..btn { background: var(--cta, #0ea5e9); }.tag { --brand: … }
.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)
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
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
#.spotlight {
background:
radial-gradient(circle at var(--x, 50%) var(--y, 50%), rgb(124 58 237 / 0.45), transparent 60%),
#18181b;
}<div class="spotlight" style="display: grid; place-items: center; height: 140px; border: 1px solid #27272a; border-radius: 14px;">Move the cursor over the card</div>
<script>
const card = document.querySelector('.spotlight')
card.addEventListener('pointermove', (event) => {
card.style.setProperty('--x', event.offsetX + 'px')
card.style.setProperty('--y', event.offsetY + 'px')
})
</script>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")andel.style.setProperty("--brand", "#10b981"). - A variable won’t glue a unit onto a number:
var(--n)pxdoesn’t work. Usecalc(var(--n) * 1px).
Related entries
#- :rootMatches the document’s root element, the html tag in HTML. The usual place for CSS variables shared across the whole page.
- @propertyRegisters a CSS variable with a type, an initial value, and an inheritance rule. Such a variable can be animated smoothly, e.g. a gradient angle.
- calc()Computes a value from a mathematical expression and lets you combine different units, for example percentages with pixels.
- color-mix()Mixes two colours in given proportions and in a chosen colour space. It creates lighter, darker, and semi-transparent variants.
- clamp()Keeps a value between a minimum and a maximum, and lets it grow smoothly in between. The basis of fluid typography.
Practise it in lessons
#Spotted a mistake or missing an example? Write to us.