Sass Variables

What Are Sass Variables?

A Sass variable stores a value, a color, a length, a font stack, a list, or a map, under a name prefixed with $. Wherever that variable is used, the compiler substitutes its value at build time.

Unlike CSS custom properties (--brand-color), Sass variables do not exist at runtime in the browser. They are purely a compile-time convenience for keeping your source code consistent and easy to update.

$primary-color: #2563eb;
$spacing-md: 1rem;

.button {
  background-color: $primary-color;
  padding: $spacing-md;
}

Changing $primary-color once updates every rule that references it, no need to find and replace the color across the file.

Variable Declaration Syntax

$name: value;
$name: value !default;
$name: value !global;

• Variable names start with $, followed by a name using letters, numbers, and hyphens.
• !default assigns a value only if the variable is not already defined, useful for configurable defaults.
• !global forces an assignment inside a block to affect the global scope instead of a local one.
• Variable values can be any Sass data type: colors, numbers, strings, lists, maps, or booleans.

Sass Variables Cheatsheet

Common variable patterns you will use across nearly every Sass project.

Variable Scope in Sass

Variables declared at the top level of a file are global and available anywhere below their declaration in that file (and in files that load it, once shared through modules). Variables declared inside a selector, mixin, or function are local to that block by default.

$global-radius: 8px;

.card {
  $local-padding: 1rem; // only exists inside .card
  padding: $local-padding;
  border-radius: $global-radius;
}

// $local-padding is not accessible here

Local variables shadow same-named global variables only within their own block.

Default Values With !default

The !default flag is essential for building configurable, reusable Sass files. It assigns a value only if the variable hasn't already been set, which lets consumers override configuration before loading your file.

// _config.scss
$border-radius: 4px !default;

// consumer.scss
$border-radius: 12px; // set before loading _config.scss
@use 'config'; // config's !default assignment is skipped

This pattern powers configurable libraries and frameworks, including how Bootstrap's Sass source lets you override variables before importing it.

Sharing Variables Across Files

In the modern module system, variables become available in another file through @use, and are accessed with a namespace prefix unless you use as * (not generally recommended, since it removes namespacing clarity).

// _colors.scss
$primary: #2563eb;

// main.scss
@use 'colors';

.button {
  background: colors.$primary;
}

The namespace (colors.) makes it clear exactly which file a shared variable came from.

Common Mistakes

• Expecting a Sass variable to update live in the browser like a CSS custom property; Sass variables are resolved once, at compile time.
• Forgetting !default, which makes a configuration file's variables impossible to override safely.
• Reassigning a variable inside a block and expecting the change to persist globally without the !global flag.
• Using unnamespaced @use ... as * everywhere, which makes it unclear where a given variable was defined.

Key Takeaways

• Sass variables ($name) store compile-time values and are substituted before the CSS reaches the browser.
• Variables declared inside a block are local by default; top-level variables are global.
• !default lets a variable be overridden by whoever loads your file first.
• The module system shares variables across files using a namespace, keeping their origin clear.