This is an experimental technology
Because this technology's specification has not stabilized, check the compatibility table for usage in various browsers. Also note that the syntax and behavior of an experimental technology is subject to change in future versions of browsers as the specification changes.

 

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 semantically 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);
}

Note: The custom property prefix was var- in the earlier spec, but later changed to --. Firefox 31 and above follow the new spec. (bug 985838)

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;
}

We'll apply it to this HTML:

<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>

which leads us to this:


Notice the repetition in the CSS. The background color is set to brown in several places. For some CSS declarations, it is possible to declare this higher in the cascade and let CSS inheritance solve this problem naturally. For non-trivial projects, this is not always possible. By declaring a variable on the :root pseudo-class, a CSS author can halt some instances of repetition by using the variable.

: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>

This leads to the same result as the previous example yet allows for one canonical declaration of the desired property.

Inheritance of CSS Variables

Custom properties do inherit. It means that if no value is set for a custom property on a given element, the value of its parent is used:

<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.

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

Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support (Yes)-webkit
33.0
No support 34.0[2]
49.0
29 (29)[3]
31 (31)
No support 36.0 9.1
Feature Android Android Webview Firefox Mobile (Gecko) IE Phone Opera Mobile Safari Mobile Chrome for Android
Basic support No support 49.0 29 (29) ? ? 9.1 49.0

[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.