- CSS Variables — The var() Function
- The Traditional Way
- Example
- Syntax of the var() Function
- How var() Works
- Example
- Example
- Browser Support
- CSS var() Function
- Using CSS custom properties (variables)
- Basic usage
- First steps with custom properties
- Using the :root pseudo-class
- Inheritance of custom properties
- Custom property fallback values
- Handling invalid custom properties
- Invalid normal properties
- HTML
CSS Variables — The var() Function
The var() function is used to insert the value of a CSS variable.
CSS variables have access to the DOM, which means that you can create variables with local or global scope, change the variables with JavaScript, and change the variables based on media queries.
A good way to use CSS variables is when it comes to the colors of your design. Instead of copy and paste the same colors over and over again, you can place them in variables.
The Traditional Way
The following example shows the traditional way of defining some colors in a style sheet (by defining the colors to use, for each specific element):
Example
.container color: #1e90ff;
background-color: #ffffff;
padding: 15px;
>
button background-color: #ffffff;
color: #1e90ff;
border: 1px solid #1e90ff;
padding: 5px;
>
Syntax of the var() Function
The var() function is used to insert the value of a CSS variable.
The syntax of the var() function is as follows:
Value | Description |
---|---|
name | Required. The variable name (must start with two dashes) |
value | Optional. The fallback value (used if the variable is not found) |
Note: The variable name must begin with two dashes (—) and it is case sensitive!
How var() Works
First of all: CSS variables can have a global or local scope.
Global variables can be accessed/used through the entire document, while local variables can be used only inside the selector where it is declared.
To create a variable with global scope, declare it inside the :root selector. The :root selector matches the document’s root element.
To create a variable with local scope, declare it inside the selector that is going to use it.
The following example is equal to the example above, but here we use the var() function.
First, we declare two global variables (—blue and —white). Then, we use the var() function to insert the value of the variables later in the style sheet:
Example
.container color: var(—blue);
background-color: var(—white);
padding: 15px;
>
button background-color: var(—white);
color: var(—blue);
border: 1px solid var(—blue);
padding: 5px;
>
Advantages of using var() are:
- makes the code easier to read (more understandable)
- makes it much easier to change the color values
To change the blue and white color to a softer blue and white, you just need to change the two variable values:
Example
.container color: var(—blue);
background-color: var(—white);
padding: 15px;
>
button background-color: var(—white);
color: var(—blue);
border: 1px solid var(—blue);
padding: 5px;
>
Browser Support
The numbers in the table specify the first browser version that fully supports the var() function.
CSS var() Function
Using CSS custom properties (variables)
Custom properties (sometimes referred to as CSS variables or cascading variables) are entities defined by CSS authors that 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 color might be used in hundreds of different places, requiring global search and replace if that color needs to change. Custom properties 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 other contexts.
Custom properties are subject to the cascade and inherit their value from their parent.
Note: Variables do not work inside media queries and container queries. The var() function can be used in place of any part of a value in any property on an element. The var() function cannot be used as property names, selectors, or anything else besides property values. So, we can’t use it in a media query or container query.
Basic usage
Declaring a custom property is done using a custom property name that begins with a double hyphen ( — ), and a property value that can be any valid CSS value. Like any other property, this is written inside a ruleset, like so:
element --main-bg-color: brown; >
Note that the selector given to the ruleset defines the scope that the custom property can be used in. A common best practice is to define custom properties on the :root pseudo-class, so that it can be applied globally across your HTML document:
However, this doesn’t always have to be the case: you maybe have a good reason for limiting the scope of your custom properties.
Note: Custom property names are case sensitive — —my-color will be treated as a separate custom property to —My-color .
As mentioned earlier, you use the custom property value by specifying your custom property name inside the var() function, in place of a regular property value:
element background-color: var(--main-bg-color); >
First steps with custom properties
Let’s start with this CSS that applies the same color to elements of different classes:
.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">1:div> div class="two">2: Text span class="five">5 - more textspan>div> input class="three" /> textarea class="four">4: Lorem Ipsumtextarea> div>
This produces the following result:
Using the :root pseudo-class
Notice the repetitive CSS in the example above. 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 custom property on the :root pseudo-class and using it where needed throughout the document, a CSS author can reduce the need for repetition:
: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 textspan>div> input class="three" /> textarea class="four">Lorem Ipsumtextarea> div>
This leads to the same result as the previous example, yet allows for one canonical declaration of the desired property value; very useful if you want to change the value across the entire page later.
Inheritance of custom properties
Custom properties do inherit. This means that if no value is set for a custom property on a given element, the value of its parent is used. Take this HTML:
div class="one"> div class="two"> div class="three">div> div class="four">div> div> div>
.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
Keep in mind that these are custom properties, not actual variables like you might find in other programming languages. The value is computed where it is needed, not stored for use in other rules. For instance, you cannot set a property for an element and expect to retrieve it in a sibling’s descendant’s rule. The property is only set for the matching selector and its descendants, like any normal CSS.
Custom property fallback values
Using the var() function, you can define multiple fallback values when the given variable is not yet defined; this can be useful when working with Custom Elements and Shadow DOM.
Note: Fallback values aren’t used to fix the browser compatibility. If the browser doesn’t support CSS custom properties, the fallback value won’t help. It’s just a backup for the browser which supports CSS custom properties to choose a different value if the given variable isn’t defined or has an invalid value.
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. The function only accepts two parameters, assigning everything following the first comma as the second parameter. If that second parameter is invalid, the fallback will fail. For example:
.two /* Red if --my-var is not defined */ color: var(--my-var, red); > .three /* pink if --my-var and --my-background are not defined */ background-color: var(--my-var, var(--my-background, pink)); > .three /* Invalid: "--my-background, pink" */ background-color: var(--my-var, --my-background, pink); >
Including a custom property as a fallback, as seen in the second example above, is the correct way to provide more than one fallback. The technique has been seen to cause performance issues as it takes more time to parse through the variables.
Note: The syntax of the fallback, like that of custom properties, allows commas. For example, var(—foo, red, blue) defines a fallback of red, blue — anything between the first comma and the end of the function is considered a fallback value.
Handling invalid custom properties
Each CSS property can be assigned a defined set of values. If you try to assign a value to a property that is outside its set of valid values, it’s considered invalid.
When the browser encounters an invalid value for a normal property, it discards the value, and elements are assigned the values that they would have had if the declaration simply did not exist.
However, when the values of custom properties are parsed, the browser doesn’t yet know where they will be used, so it must 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.
When the browser encounters an invalid var() substitution, then the initial or inherited value of the property is used.
The next two examples illustrate this.
Invalid normal properties
In this example we attempt to apply a value of 16px to the color property. Because this is invalid, the CSS is discarded and the result is as if the rule did not exist, so the previous color: blue rule is applied instead, and the paragraph is blue.
HTML
p>This paragraph is initially black.p>