CSS Variables

Imagine your website uses the same green colour in twenty places — headings, buttons, links, borders, and the header background. Then one day you want to change that green to blue. Without variables, you must hunt down all twenty places and change each one, hoping you do not miss any. With CSS variables, you change one line and the whole site updates at once.

Diagram — see how it fits together

A CSS variable, also called a custom property, is a value you store under a name and reuse anywhere in your stylesheet. You define it once, and every rule that uses it picks up the value automatically.

Defining and using a variable

A variable name always starts with two dashes, like --main-color. The usual place to define it is :root, which means the top of the document — a variable defined there is available everywhere. You read the value back with the var() function.

Syntax — one colour, used everywhere

:root {
  --main-color: #04aa6d;
  --dark-color: #333;
}
h1 { color: var(--main-color); }
button {
  background-color: var(--main-color);
  color: white;
}

Now the heading and the button share the same green. Change --main-color in :root from green to blue, and both change together. That single line is the whole theme.

Changing a theme with one value

Because a variable is just a value, you can build an entire colour theme from a handful of them: --main-color for the brand colour, --bg-color for page backgrounds, --text-color for text, and --accent-color for highlights. A dark section of the page can even redefine the same variables locally — inside that section, --bg-color becomes dark and --text-color becomes white, while the rest of the page stays light.

.dark-box {
  --bg-color: #333;
  --text-color: white;
  background-color: var(--bg-color);
  color: var(--text-color);
}

Common mistakes

• Forgetting the two dashes — main-color without -- is not a variable, and the browser will ignore it.
• Writing var(main-color) without the dashes inside var() — the name inside must match exactly, dashes included.
• Defining a variable inside one element and trying to use it somewhere else on the page — it only works in that element and its children.
• Naming a variable after its value, like --green — when the colour changes, the name lies.
• Forgetting that variable names are case-sensitive — --Main-Color and --main-color are two different variables.

Remember

• A CSS variable is a custom property: a value stored under a name starting with --.
• Define theme variables in :root so the whole page can use them.
• Read a variable with var(--name), for example var(--main-color).
• Change one value in :root and every rule using it updates at once.
• Name variables by purpose (--main-color), not by value (--green).

Example explained

• :root { --main-color: #04aa6d; } — the theme is defined once at the top of the document: the brand green, a dark grey, a light background, and a text colour.
• h1 { color: var(--main-color); } — the heading reads the brand colour from the variable instead of writing the colour code directly.
• button { background-color: var(--main-color); } — the button uses the very same variable, so the heading and the button always match.
• .dark-box { --bg-color: #333; --text-color: white; } — inside the dark box the background and text variables are redefined, so only that box turns dark while the rest of the page stays light.
• var(--main-color, blue) — the second value inside var() is a fallback: if the variable were ever missing, blue would be used instead.