CSS custom properties (formerly known as CSS variables) are a powerful feature that allows developers to define and reuse values throughout their stylesheets. They provide a way to store and manage values in a more flexible and efficient manner, bringing modularity and extensibility to CSS.

In this article, we are going to talk about CSS custom properties by comparing with SASS variables.

SASS variables & CSS Custom Properties

If you come from the SASS world, you’re likely familiar with SASS variables. In the realm of CSS, SASS variables and CSS custom properties share similarities but also offer different features and solutions. In this article, we’ll explore the definitions of SASS variables and CSS custom properties, highlight their main differences, and discuss about choosing the appropriate solution for your needs.

Defining SASS variables & CSS custom properties

Sass variables

SASS variables are declared using the $ symbol followed by the variable name. They allow us to assign values and reuse them throughout the stylesheet.

From the example below, $primary-color is a global variable as it is declared at the top level of a stylesheet. To use the variable, we can simply use it as a value, background-color: $primary-color.

$primary-color: hsla(40, 92%, 60%, 1);

.box {
  background-color: $primary-color;
}

CSS custom properties

CSS custom properties, also known as CSS variables, are denoted by a double hyphen (--) followed by the property name. The CSS working group decided the double hyphen instead of $ because they wanted developers to use both SASS variables and CSS custom properties.

Unlike SASS variables, CSS custom properties are typically defined within the :root pseudo-class to ensure global accessibility. If you define the custom property at the top level of the stylesheet like Sass variable, you won’t get the custom property working properly.

Additionally, to utilise the value of a CSS custom property, we use the var() function.

:root {
  --primary-color: hsla(40, 92%, 60%, 1);
}

.box {
  background-color: var(--primary-color);
}

Mixing usage

Sass variables

We can use a Sass variable as the value of another Sass variable. Let’s see the following example:

$yellow: hsla(40, 92%, 60%, 1);
$primary-color: $yellow;

.box {
  background-color: $primary-color;
}

Similarly, we can use a CSS custom property as the value of a Sass variable. Take a look at this example:

$primary-color: var(--yellow);

:root {
  --yellow: hsla(40, 92%, 60%, 1);
}

.box {
  background-color: $primary-color;
}

Interestingly, the declaration of the --yellow custom property in the :root pseudo-class can be physically located below the $primary-color Sass variable. This is because Sass variables are resolved at compile time, while CSS custom properties are resolved at runtime by the browser.

During Sass compilation, the $primary-color variable is assigned the string value var(--yellow). When the browser encounters this CSS code, it interprets var(--yellow) as a CSS custom property reference and resolves it to the value defined in the :root selector.

As a result, the Sass variable $primary-color indirectly references the CSS custom property --yellow.

CSS custom properties

We can also use CSS custom properties as the value of other custom properties. Let’s see the following example:

:root {
  --yellow: hsla(40, 92%, 60%, 1);
  --primary-color: var(--yellow);
}

.box {
  background-color: var(--primary-color);
}

If we want to use a Sass variable directly as the value of a custom property, we need to use interpolation. Without interpolation, it won’t work as expected. Here’s an example:

$yellow: hsla(40, 92%, 60%, 1);

:root {
  --primary-color: #{$yellow};
}

.box {
  background-color: var(--primary-color);
  width: 100px;
  height: 100px;
}

In this case, we use #{$yellow} for interpolation to ensure that the value of the Sass variable is correctly interpreted as the value of the --primary-color custom property.

Default value

Sass variable

In Sass, default values can be assigned using the !default flag.

Let’s consider a scenario where we have a button component library with a default pink primary colour, but we want to use orange as the primary colour for our brand. Here’s how it can be implemented (note: for the Sass structure, we follow the ITCSS, so it will look like below).

// (Settings) Our brand
$primary-color: orange;

// (Vendors) Super simple button component library
$primary-color: pink !default;

.button {
  background-color: $primary-color;
}

In this example, the button background colour will be orange. The $primary-color variable in the library has the !default flag, indicating that it will be ignored if it is already declared prior. If it’s not declared, the primary colour will default to pink.

CSS custom properties

Unlike SASS variables, CSS custom properties do not inherently provide a mechanism for default values. However, fallback values can be specified using the var() function.

The var() function accept the second argument, declaration-value as a fallback value. Consider the following approach:

// (Settings) Our brand
:root {
  --primary-color: orange;
}

// (Vendors) Super simple button component library
.library-root {
  --library-primary-color: pink;
}

.button {
  background-color: var(--primary-color, var(--library-primary-color));
}

In this example, we set the --primary-color custom property to orange for our brand. Within the library, we declare a different custom property, --library-primary-color, to avoid overwriting --primary-color.

The background-color property of the button uses the var() function with --primary-color as the first argument and --library-primary-color as the fallback value. The var() function allows us to access the custom property value, providing a fallback if the primary color is not defined.

Local scope

Sass variables

Sass variables declared in a block can only be accessed within that same block. Let’s see the example:

.container {
  $bg-color: orange;
}

.box {
  background-color: $bg-color;
}

In the above Sass code example, we will encounter an “Undefined variable” error because $bg-color can only be used within the .container block, even if it is a parent of the .box element. To make it work, we need to ensure that the variable is in the same scope as its usage:

.box {
  $bg-color: orange;

  background-color: $bg-color;
}

Alternatively, we can declare the variable outside the block to make it a global variable that can be accessed from any place:

$bg-color: orange;

.container {
  background-color: $bg-color;
}

.box {
  background-color: $bg-color;
}

CSS custom properties

CSS custom properties inherit CSS features, such as cascading and inheritance. Let’s revisit the same example, but using custom properties:

.container {
  --bg-color: orange;
}

.box {
  background-color: var(--bg-color);
}

In this case, the custom property --bg-color defined in the .container block can be accessed by the .box element, which is a child of the container. This is because custom properties are subject to the cascade and inherit their value from their parent.

Imperative vs Declarative

Sass variables

Let’s consider two boxes in HTML:

and define Sass variables:

$bg-color: orange;

.box1 {
  background-color: $bg-color;
}

$bg-color: blue;

.box2 {
  background-color: $bg-color;
}

With the above CSS code, .box1 will receive an orange background, while .box2 will have a blue background. This is because Sass variables are imperative, meaning if you use a variable and then change its value, the earlier uses of the variable will remain the same.

In this case, the first occurrence of $bg-color retains its initial value of orange, even though it was changed later to blue. Hence, box1 still receives the orange background.

Now let’s explore how CSS custom properties work differently.

CSS custom properties

Using the same HTML structure, consider the following CSS code:

:root {
  --bg-color: orange;
}

.box {
  background-color: var(--bg-color);
}

:root {
  --bg-color: blue;
}

.box2 {
  background-color: var(--bg-color);
}

In this case, both box1 and box2 will have a blue background. This is because CSS custom properties are declarative, meaning that if you change the value, it will affect both earlier and later uses.

Unlike Sass variables, the CSS custom property --bg-color retains the updated value of blue throughout the entire code. Thus, both box1 and box2 will receive the blue background colour.

This distinction arises from the imperative nature of Sass variables, where changes to a variable’s value only impact later uses within the same scope, versus the declarative behaviour of CSS custom properties, where value changes affect all occurrences, regardless of their order.

With calc()

Sass variables

The calc() CSS function provides a powerful feature that allows us to perform calculations within CSS. For example, let’s say we want to set the box width to be 20 pixels smaller than 50% of the screen size.

Without the calc() function, achieving this solely with CSS was challenging, and even with JavaScript, it could be cumbersome to obtain the correct value. However, now we can achieve it purely with CSS with the calc() function.

The following code example demonstrates how it works:

.box {
  width: calc(50% - 20px);
}

Now, let’s use 20px as a Sass variable:

$width-offset: 20px;

.box {
  width: calc(50% - $width-offset);
}

However, this will result in an error: “Invalid property value.”

As shown in the error screenshot, the Sass variable itself was added directly within the calc() function, making it unreadable by the browser.

To fix this, as we saw in the previous section, we need to use interpolation:

$width-offset: 20px;

.box {
  width: calc(50% - #{$width-offset});
}

and with the updated code, it now works correctly.

CSS custom properties

CSS custom properties work seamlessly with calc():

:root {
  --width-offset: 20px;
}

.box {
  width: calc(50% - var(--width-offset));
}

The above code naturally works without requiring any interpolation.

Invalid values

Sass variables

Sass is a pre-processor that compiles into CSS, and invalid Sass variables will simply be compiled as property values. Let’s take a look at an example:

$color: 16px;

div {
  color: blue;
}

div {
  color: $color;
}

In this case, the last div using the $color variable takes precedence. However, when we inspect it, we encounter an error stating “Invalid property value,” as shown in the image.

The reason is that Sass compiles $color: 16px as the colour value, which is invalid. CSS treats the invalid rule as if it doesn’t exist, so the previous rule color: blue is applied, resulting in the text colour inside the <div> being blue.

CSS custom properties

Now, let’s explore how CSS custom properties handle this situation with the same <div>:

// Custom properties
:root {
  --color: 16px;
}

div {
  color: blue;
}

div {
  color: var(--color);
}

Which colour do you think the text inside the <div> will receive?

It will be black. Let’s delve into the details.

As CSS custom properties are resolved at runtime by the browser, when we inspect the div, we see that var(--color) is still present as a value of color.

Due to the higher precedence of this div compared to the other one with the blue colour, the blue colour gets crossed out.

When we inspect the --color inside the var(), it displays 16px.

However, 16px is not a valid property value for color. So the browser goes through two steps:

It checks if the color property is inheritable. If it is, it takes the value from its parent. If not, it proceeds to the next step. In this case, it has no parent, so it moves on to the next step.
It sets the value to its default initial value, resulting in the text color being black for this example.

Map vs overriding properties

Sass variables

In Sass, we can map to organise variables in one place. Let’s consider an example of managing different variations of a button theme using a map:

In the above code, we manage button variations using a map:

$button-variations: (
  primary: (
    background-color: #7184c7,
    background-color-active: #6472a9,
    color: #000
  ),
  secondary: (
    background-color: #ead238,
    background-color-active: #cab94e,
    color: #000
  ),
  tertiary: (
    background-color: #facad2,
    background-color-active: #cdadb4,
    color: #000
  )
);

To assign values from the map, we can use the map-get(). For example:

background-color: map-get($property, background-color);

By iterating over the $button-variations using the @each rule, we can create different button variations such as

.button--primary
.button-secondary
.button-tertiary

If we want to add another variation, like button-warning, we can simply add the details to the $button-variations map.

$button-variations: (
  ...
  warning: (
    background-color: #c00,
    background-color-active: #841c14,
    color: #fff
  )
);

Sass maps provide flexibility in managing variables within a complex structure. However, they can be challenging to digest at first.

Now let’s consider how we can achieve the same with CSS custom properties.

CSS custom properties

CSS custom properties don’t offer the same map-like functionality as Sass, but we can override the custom property values in each scope. Let’s see how we can achieve the same result using CSS custom properties:

First, we add the .button class to each button element to set the base styles:

.button {
  --button-background-color: #c3c3c3;
  --button-background-color-active: #808080;
  --button-color: #000;

  background-color: var(--button-background-color);
  color: var(--button-color);
  outline: none;
  transition: background-color 0.3s ease-out;

  &:focus,
  &:hover,
  &:active {
    box-shadow: inset 0 0 0 0 rgba(0, 0, 0, 0), 0 0 0 2px #cceffb,
      0 0 0 4px #63b1f9;
  }

  &:active {
    background-color: var(--button-background-color-active);
  }
}

So the buttons will look like below without applying the variation styles.

Now for each variation, we can just override the custom properties then as we saw in the “Imperative vs Declarative” section above, the earlier version of the styles set in the .button will also get updated for each variation.

.button--primary {
  --button-background-color: #7184c7;
  --button-background-color-active: #6472a9;
  --button-color: #000;
}

.button--secondary {
  --button-background-color: #ead238;
  --button-background-color-active: #cab94e;
  --button-color: #000;
}

.button--tertiary {
  --button-background-color: #facad2;
  --button-background-color-active: #cdadb4;
  --button-color: #000;
}

By overriding the custom properties for each variation, like .button--primary, .button--secondary, and .button--tertiary, we update the .button styles accordingly.

If we want to add another variation, such as button-warning, we can add the modifier class and override the custom properties accordingly.

.button--warning {
  --button-background-color: #c00;
  --button-background-color-active: #841c14;
  --button-color: #fff;
}

The approach of managing variations using Sass maps and CSS custom properties differs, but the approach with CSS custom properties is more intuitive and provides a clearer and more straightforward solution.

Updating values with JavaScript

Sass variables

Sass is a pre-processor that compiles into CSS. Once the Sass code is compiled into CSS, JavaScript can no longer directly access Sass variables.

While there might be libraries that allow accessing Sass variables from JavaScript during compilation, it is not possible natively.

CSS custom properties

In JavaScript, we can both retrieve and update the values of CSS custom properties.

Let’s start with retrieving the property value using JavaScript. To retrieve the transition value of the .button--primary element from the example code, we can do the following:

const primaryButton = document.querySelector('.button--primary');

const primaryButtonBgColor = getComputedStyle(primaryButton).getPropertyValue("transition");

console.log(primaryButtonBgColor);

By first obtaining the computed style of the element (getComputedStyle(primaryButton)), we can retrieve the desired property value (transition) using getPropertyValue("transition").

The output will be:

background-color 0.3s ease-out 0s

Similarly, to retrieve the value of a custom property (as the name suggests, it is a property too), we follow the same approach. To retrieve the value of --button-background-color from the .button--primary element, we can do:

const primaryButton = document.querySelector('.button--primary');

const primaryButtonBgColor = getComputedStyle(primaryButton).getPropertyValue("--button-background-color");

console.log(primaryButtonBgColor);

and the output will be:

#7184c7

To update the value of a custom property, we can use the setProperty method:

const primaryButton = document.querySelector('.button--primary');

primaryButton.style.setProperty("--button-background-color", "#ddeb90");

And when we check the custom property value again:

const primaryButtonBgColor = getComputedStyle(primaryButton).getPropertyValue("--button-background-color");

// output: #ddeb90
console.log(primaryButtonBgColor);

So which one to use?

Sass provides many great features like @function, @extend, @mixin and @include. However, when it comes to variables, I prefer to use CSS custom properties. CSS custom properties align with native CSS features like specificity, inheritance, and cascading. They allow us to manage properties in a more CSS-oriented way and improve the maintainability of our CSS workflow, which is crucial for the frontend development. Plus we can update its value from JavaScript too 😉