What are CSS variables?

The CSS variables are more accurately known as CSS custom properties. You can define a value under a variable key and use it along your stylesheets wherever is in its scope. They can be very useful to avoid CSS repetition, with a better performance in run time for things like theme switching and very useful for extending or ‘polyfilling’ future CSS features.

Maybe you used or saw the use of variables in preprocessors like Sass or Less but there are some differences in the use. Unlike the way the variables are set and used in preprocessors which are only available in compilation time you can use the CSS custom properties during ‘execution’ time so the browser can update the things displayed accordingly the changes.

Sass Less

The CSS custom properties are currently defined as a candidate recommendation in the W3C.org

W3C Custom properties

But are widely implemented among the browsers and you’re close to be sure to use them in your projects

About custom properties in caniuse

How to define CSS variables?

You can define the CSS variables inside any common CSS selector you are using in your stylesheets with a simple -- following the css name for that variable and the value for that variable after the : property assignation. As you are defining them into a CSS selector, the value will be applied in cascade in the same way any other property would apply. The value there will be defined there in the same way you declare any CSS property value.

A practical way to use it is making them accessible over all your stylesheet so you can define them into the root of the document using the :root pseudo element.

:root {
  --your-color-variable-1: coral;
  --your-color-variable-2: blue;
  --your-border-default-setting: 1px solid black;
}

How to use CSS variables?

After your declaration you can use them inside the scope of the selector you defined it with the var() function, using as parameter the property in the same way you declared it (with the two preceding dashes).

As easy as this:

.your-classname {
  color: var(--your-color-variable-1, 'coral');
  border: var(--your-border-default-setting);
}

Note the second argument in the use of the var for the color property. You can provide there also a default value in case your variable is not defined yet. This can happen if, for example, you are setting it via Javascript after the first render of the web view

How to manipulate CSS variables?

After you set your variables you can manipulate it as you would do with the css properties in Javascript.

You can go by the style property of an element and use the getPropertyValue on that property to get the value as a String.

element.style.getPropertyValue('--your-color-variable-1')

Also, you can get the computed style for an element using the getComputedStyle function available on the global window object and also use the getPropertyValue on the style object retrieved.

getComputedStyle(element).getPropertyValue('--your-color-variable-1')

To set a CSS variable via Javascript you can use the setProperty method for the style object:

element.style.setProperty('--your-color-variable-1', '#ff0000')

You should remember the value will apply on cascade so only will affect those elements in the scope of that declaration.

You can check the following embedded Codepen to see an example of how the values are changed via Javacript and the value applied on cascade:

See the Pen CSS Variables by Joan Maria Talarn Espelta (@jmtalarn) on CodePen.

Theming your stylesheets

Once you know the basics of the CSS variables (AKA CSS Custom properties) you can use it as a powerful tool to declare CSS themes, without the need of complex stylesheet manipulation. You only need to identify recurrent properties you use in your CSS stylesheets, or those properties susceptibles to be changed depending on the theme like box shadows, text shadows or even the animations defined in your transitions properties.

After that a simple Javascript call to change the css variables on the root of the stylesheet will be enough to change it over all your site using them.

The values for your document root can be got from the computed style over your document body.

const rootStyles = window.getComputedStyle(document.body)
let titleColor = rootStyles.getPropertyValue('--title-color').trim()

let subtitleColor = rootStyles.getPropertyValue('--subtitle-color').trim()

And after that you can set it as you want in a similar way as described before:

const cssVar = '--title-color'
const newCssValue = 'pink' //or any other value you need to set
document.documentElement.style.setProperty(cssVar, newCssValue)