sass-site/source/documentation/breaking-changes/css-vars.html.md.erb

---
title: "Breaking Change: CSS Variable Syntax"
introduction: >
  Older versions of LibSass and Ruby Sass parsed custom property declarations
  just like any other property declaration, allowing the full range of
  [SassScript expressions](../syntax/structure#expressions) as values. But this
  wasn't compatible with CSS.
---

<% impl_status dart: true, libsass: '3.5.0', ruby: '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:

[Polymer library]: https://polymer-library.polymer-project.org/3.0/docs/devguide/custom-css-properties#use-custom-css-mixins

<% example(syntax: :scss) do %>
  :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);
    };
  }
  ===
  :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);
    };
  }
<% end %>

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). Interpolation will also work for older Sass
versions, and so is recommended for all stylesheets.

<% example do %>
  $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};
  }
  ===
  $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}
  ===
  :root {
    --accent-color-wrong: $accent-color;
    --accent-color-right: #fbbc04;
  }
<% end %>

<% heads_up do %>
  Because interpolation removes quotation marks from quoted strings, it may be
  necessary to wrap them in the [`inspect()` function][] to preserve their
  quotes.

  [`inspect()` function]: ../modules/meta#inspect

  <% example do %>
    $font-family-monospace: Menlo, Consolas, "Courier New", monospace;

    :root {
      --font-family-monospace: #{inspect($font-family-monospace)};
    }
    ===
    $font-family-monospace: Menlo, Consolas, "Courier New", monospace

    :root
      --font-family-monospace: #{inspect($font-family-monospace)}
  <% end %>
<% end %>