Breaking Change: CSS Variable Syntax

Older versions of LibSass and Ruby Sass parsed custom property declarations just like any other property declaration, allowing the full range of SassScript expressions as values. But this wasn’t compatible with CSS.

Compatibility:
Dart Sass
✓
LibSass
since 3.5.0
Ruby Sass
since 3.5.0

The CSS spec allows almost any string of characters to be used in a custom property declaration. Even though these values might not be meaningful for any CSS property, they could be accessed from JavaScript. When they were parsed as SassScript values, syntax that would have been valid plain CSS failed to parse. For example, the Polymer library used this to support plain-CSS mixins:

Playground

SCSS Syntax

:root {
  --flex-theme: {
    border: 1px solid var(--theme-dark-blue);
    font-family: var(--theme-font-family);
    padding: var(--theme-wide-padding);
    background-color: var(--theme-light-blue);
  };
}

CSS Output

:root {
  --flex-theme: {
    border: 1px solid var(--theme-dark-blue);
    font-family: var(--theme-font-family);
    padding: var(--theme-wide-padding);
    background-color: var(--theme-light-blue);
  };
}

To provide maximum compatibility with plain CSS, more recent versions of Sass require SassScript expressions in custom property values to be written within interpolation. Interpolation will also work for older Sass versions, and so is recommended for all stylesheets.

Playground

SCSS Syntax

$accent-color: #fbbc04;

:root {
  // WRONG, will not work in recent Sass versions.
  --accent-color-wrong: $accent-color;

  // RIGHT, will work in all Sass versions.
  --accent-color-right: #{$accent-color};
}
Playground

Sass Syntax

$accent-color: #fbbc04

:root
  // WRONG, will not work in recent Sass versions.
  --accent-color-wrong: $accent-color

  // RIGHT, will work in all Sass versions.
  --accent-color-right: #{$accent-color}

CSS Output

:root {
  --accent-color-wrong: $accent-color;
  --accent-color-right: #fbbc04;
}

⚠️ Heads up!

Because interpolation removes quotation marks from quoted strings, it may be necessary to wrap them in the meta.inspect() function to preserve their quotes.

Playground

SCSS Syntax

@use "sass:meta";

$font-family-monospace: Menlo, Consolas, "Courier New", monospace;

:root {
  --font-family-monospace: #{meta.inspect($font-family-monospace)};
}
Playground

Sass Syntax

@use "sass:meta"

$font-family-monospace: Menlo, Consolas, "Courier New", monospace

:root
  --font-family-monospace: #{meta.inspect($font-family-monospace)}

CSS Output

:root {
  --font-family-monospace: Menlo, Consolas, "Courier New", monospace;
}