Using CSS variables

CSS Variables are entities defined by CSS authors which contain specific values to be reused throughout a document. They are set using custom property notation (e.g. --main-color: black;) and are accessed using the var() function (e.g. color: var(--main-color);) .

Complex websites have very large amounts of CSS, often with a lot of repeated values. For example, the same colour might be used in hundreds of different places, requiring global search and replace if that colour needs to change. CSS variables allow a value to be stored in one place, then referenced in multiple other places. An additional benefit is semantic identifiers. For example --main-text-color is easier to understand than #00ff00, especially if this same color is also used in another context.

CSS Variables are subject to the cascade, and inherit their value from their parent.

Basic usage

Declaring a variable:

element {
  --main-bg-color: brown;
}

Using the variable:

element {
  background-color: var(--main-bg-color);
}

First steps with CSS Variables

Let's start with this simple CSS that colors elements of different classes with the same color:

.one {
  color: white;
  background-color: brown;
  margin: 10px;
  width: 50px;
  height: 50px;
  display: inline-block;
}
.two {
  color: white;
  background-color: black;
  margin: 10px;
  width: 150px;
  height: 70px;
  display: inline-block;
}
.three {
  color: white;
  background-color: brown;
  margin: 10px;
  width: 75px;
}
.four {
  color: white;
  background-color: brown;
  margin: 10px;
  width: 100px;
}
.five {
  background-color: brown;
}

<div>
    <div class="one"></div>
    <div class="two">Text <span class="five">- more text</span></div>
    <input class="three">
    <textarea class="four">Lorem Ipsum</textarea>
</div>

:root {
  --main-bg-color: brown;
}
.one {
  color: white;
  background-color: var(--main-bg-color);
  margin: 10px;
  width: 50px;
  height: 50px;
  display: inline-block;
}
.two {
  color: white;
  background-color: black;
  margin: 10px;
  width: 150px;
  height: 70px;
  display: inline-block;
}
.three {
  color: white;
  background-color: var(--main-bg-color);
  margin: 10px;
  width: 75px;
}
.four {
  color: white;
  background-color: var(--main-bg-color);
  margin: 10px;
  width: 100px;
}
.five {
  background-color: var(--main-bg-color);
}

<div>
    <div class="one"></div>
    <div class="two">Text <span class="five">- more text</span></div>
    <input class="three">
    <textarea class="four">Lorem Ipsum</textarea>
</div>

<div class="one">
  <div class="two">
    <div class="three"></div>
    <div class="four"></div>
  </div>
</div>

with the following CSS:

.two {
  --test: 10px;
}
.three {
  --test: 2em;
}

In this case, the results of var(--test) are:

• for the class="two" element: 10px
• for the class="three" element: 2em
• for the class="four" element: 10px (inherited from its parent)
• for the class="one" element: invalid value, which is the default value of any custom property.

Using var() you can define mutiple fallback values when the given variable is not yet defined, this can be useful when working with Custom Elements and Shadow DOM.

The first argument to the function is the name of the custom property to be substituted. The second argument to the function, if provided, is a fallback value, which is used as the substitution value when the referenced custom property is invalid. E.g:

.two {
  color: var(--my-var, red); /* Red if --my-var is not defined */
}
.three {
  background-color: var(--my-var, var(--my-background, pink)); /* pink if my-var and --my-background are not defined */
}
.three {
  background-color: var(--my-var, --my-background, pink); /* Invalid: "--background, pink" */
}

Validity and values

The classical CSS concept of validity, tied to each property, is not very useful in regard to custom properties. When the values of the custom properties are parsed, the browser doesn't know where they will be used, so must therefore consider nearly all values as valid.

Unfortunately, these valid values can be used, via the var() functional notation, in a context where they might not make sense. Properties and custom variables can lead to invalid CSS statements, leading to the new concept of valid at computed time.

Browser compatibility

[1] Chrome initially implemented this feature using a different syntax, which required to prefix custom property names with -webkit-var- to define them. They could then be used unprefixed within a -webkit-var() function. Additionally, the implementation was hidden behind the Enable experimental WebKit features flag under chrome://flags, later renamed to Enable experimental Web Platform features.

[2] Chrome 34.0 removed this feature due to performance issues.

[3] This feature is implemented behind the preference layout.css.variables.enabled, defaulting to false and using the old var-variablename syntax in Gecko 29. Starting from Gecko 31 the preference is enabled by default and the new --variablename syntax is used. From Gecko 55, the layout.css.variables.enabled preference has been removed completely so the feature is enabled all the time and can no longer be disabled.