Sass Variables

What You’ll Learn

Sass variables store values under $names. This page covers declarations, Sass vs CSS variables, scope, !default, !global, maps instead of dynamic names, and five compiled examples.

What Are Sass Variables?

Official docs: assign a value to a name that begins with $, then refer to that name instead of repeating the value. Variables reduce repetition, enable math and theming, and help configure libraries.

A declaration looks like a property ($name: value;) but can appear almost anywhere—not only inside style rules.

• Compiled away—the CSS file contains the final values, not $names.
• Imperative: using a variable snapshots its current value.
• Hyphens and underscores are equivalent ($font-size = $font_size).
• Cannot invent variable names with interpolation—use a map instead.

📝 Syntax

$base-color: #c6538c;
$border-dark: rgba($base-color, 0.88);

.alert {
  border: 1px solid $border-dark;
}

⚖️ Sass Variables vs CSS Variables

Official docs: CSS has its own variables (--token), and they are totally different from Sass $variables.

⚡ Default Values (!default)

Official docs: normally a new assignment overwrites the old value. With !default, Sass assigns only if the variable is undefined or null. Libraries use this so consumers can configure tokens first.

With @use, you can also configure module defaults: @use "library" with ($black: #222);

🏢 Scope, Shadowing & !global

• Top-level variables are global within their module.
• Inside blocks (rules, mixins, …) variables are usually local.
• Shadowing — a local $name can hide a global one without changing it.
• !global — assign to the existing top-level variable from inside a block.

Flow control scope: variables inside @if / loops do not shadow outer variables at the same level—they assign to them. Declare the variable first (even as null) before conditionally updating it.

🧮 Built-ins & Dynamic Names

Variables from built-in modules (like math.$pi) cannot be reassigned. For “dynamic variable names,” store values in a map and look them up with map.get—Sass does not allow $theme-#{$name} style declarations.

Helpers such as meta.variable-exists() and meta.global-variable-exists() can inspect the current or global scope when needed.

Examples Gallery

Each example shows a core variable behavior. Open View Compiled CSS for verified output.

$base-color: #c6538c;
$border-dark: rgba($base-color, 0.88);

.alert {
  border: 1px solid $border-dark;
}

.alert {
  border: 1px solid rgba(198, 83, 140, 0.88);
}

$variable: value 1;
.rule-1 {
  value: $variable;
}

$variable: value 2;
.rule-2 {
  value: $variable;
}

.rule-1 {
  value: value 1;
}

.rule-2 {
  value: value 2;
}

$global-variable: global value;

.content {
  $local-variable: local value;
  global: $global-variable;
  local: $local-variable;
}

.sidebar {
  global: $global-variable;
  // $local-variable is not available here
}

.content {
  global: global value;
  local: local value;
}

.sidebar {
  global: global value;
}

$variable: first global value;

.content {
  $variable: second global value !global;
  value: $variable;
}

.sidebar {
  value: $variable;
}

.content {
  value: second global value;
}

.sidebar {
  value: second global value;
}

@use "sass:color";
@use "sass:map";

$dark-theme: true !default;
$primary-color: #f8bbd0 !default;
$accent-color: #6a1b9a !default;

@if $dark-theme {
  $primary-color: color.scale($primary-color, $lightness: -60%);
  $accent-color: color.scale($accent-color, $lightness: 60%);
}

$theme-colors: (
  "success": #28a745,
  "info": #17a2b8,
  "warning": #ffc107,
);

$font_size: 16px;
$font-size: 18px; // same variable as $font_size

.button {
  background-color: $primary-color;
  border: 1px solid $accent-color;
  border-radius: 3px;
}

.alert {
  background-color: map.get($theme-colors, "warning");
}

.size {
  font-size: $font-size;
}

.button {
  background-color: #9e1041;
  border: 1px solid #c88feb;
  border-radius: 3px;
}

.alert {
  background-color: #ffc107;
}

.size {
  font-size: 18px;
}

🚀 Real-World Use Cases

• Design tokens — brand colors, spacing, radii, fonts.
• Library configuration — !default + @use … with.
• Theming — toggle flags then adjust related variables.
• DRY math — compute derived sizes from one base unit.
• Named palettes — maps when keys must be dynamic.

⚠️ Common Pitfalls

• Confusing with CSS --vars — Sass variables do not cascade in the browser.
• Expecting earlier rules to update — reassignment is imperative.
• Accidental locals — assigning inside a block without !global shadows.
• Dynamic $name-#{} — not allowed; use a map.
• Using !global to create new globals — declare at top level first.

💡 Best Practices