Sass Maps

What You’ll Learn

Sass maps store key/value pairs for easy lookups. This page covers writing maps, quoted keys, map.get / set / merge, @each loops, immutability, and five compiled examples.

What Are Sass Maps?

Official docs: maps hold pairs of keys and values so you can look up a value by its key. They are written (key: value, …). Keys must be unique; values may be duplicated. Unlike lists, maps must use parentheses. An empty map is ().

• Any Sass value can be a key; equality uses ==.
• Maps are not valid CSS by themselves—use helpers or loops to emit CSS.
• Every map also counts as a list of two-element key/value lists.
• Prefer quoted string keys to avoid color-name traps.

📝 Syntax

$font-weights: (
  "regular": 400,
  "medium": 500,
  "bold": 700,
);

$empty: (); // empty map (also an empty list)

📄 Prefer Quoted Keys

Official docs: most of the time, use quoted strings for keys. Some values that look like unquoted strings—especially color names like red—are other types. Quoting avoids confusing lookup bugs later.

🧮 Using Maps

Load @use "sass:map" for helpers:

Loop pairs with @each: @each $key, $value in $map { … }.

🔗 Maps Count as Lists

Official docs: every map is also a list containing a two-element list for each pair. For example, (1: 2, 3: 4) counts as (1 2, 3 4). That is why empty () is both an empty map and an empty list.

🔒 Immutability

Official docs: map contents never change in place. map.set and map.merge return new maps. Reassign when you need updated state: $config: map.merge($config, ("theme": dark));

Examples Gallery

Each example turns map data into CSS or inspectable values. Open View Compiled CSS for verified output.

@use "sass:map";
@use "sass:list";
@use "sass:meta";

$font-weights: ("regular": 400, "medium": 500, "bold": 700);

.lookup {
  --medium: #{meta.inspect(map.get($font-weights, "medium"))};
  --missing: #{meta.inspect(map.get($font-weights, "extra-bold"))};
  --has: #{meta.inspect(map.has-key($font-weights, "bold"))};
  --keys: #{meta.inspect(map.keys($font-weights))};
  --vals: #{meta.inspect(map.values($font-weights))};
  --pair: #{meta.inspect(list.nth($font-weights, 1))};
}

.lookup {
  --medium: 500;
  --missing: null;
  --has: true;
  --keys: "regular", "medium", "bold";
  --vals: 400, 500, 700;
  --pair: "regular" 400;
}

$icons: ("eye": "\f112", "start": "\f12e", "stop": "\f12f");

@each $name, $glyph in $icons {
  .icon-#{$name}:before {
    display: inline-block;
    font-family: "Icon Font";
    content: $glyph;
  }
}

.icon-eye:before {
  display: inline-block;
  font-family: "Icon Font";
  content: "\f112";
}

.icon-start:before {
  display: inline-block;
  font-family: "Icon Font";
  content: "\f12e";
}

.icon-stop:before {
  display: inline-block;
  font-family: "Icon Font";
  content: "\f12f";
}

@use "sass:map";
@use "sass:meta";

$font-weights: ("regular": 400, "medium": 500, "bold": 700);
$light-weights: ("lightest": 100, "light": 300);
$heavy-weights: ("medium": 500, "bold": 700);
$weights: ("light": 300, "medium": 500);

.set-merge {
  --set-new: #{meta.inspect(map.set($font-weights, "extra-bold", 900))};
  --set-replace: #{meta.inspect(map.set($font-weights, "bold", 900))};
  --merged: #{meta.inspect(map.merge($light-weights, $heavy-weights))};
  --override: #{meta.inspect(map.merge($weights, ("medium": 700)))};
  --original: #{meta.inspect($font-weights)};
}

.set-merge {
  --set-new: ("regular": 400, "medium": 500, "bold": 700, "extra-bold": 900);
  --set-replace: ("regular": 400, "medium": 500, "bold": 900);
  --merged: ("lightest": 100, "light": 300, "medium": 500, "bold": 700);
  --override: ("light": 300, "medium": 700);
  --original: ("regular": 400, "medium": 500, "bold": 700);
}

@use "sass:map";

$breakpoints: (
  "sm": 480px,
  "md": 768px,
  "lg": 1024px,
);

@each $name, $width in $breakpoints {
  @media (min-width: $width) {
    .container-#{$name} {
      max-width: $width;
    }
  }
}

.btn {
  font-weight: map.get(("regular": 400, "bold": 700), "bold");
}

@media (min-width: 480px) {
  .container-sm {
    max-width: 480px;
  }
}
@media (min-width: 768px) {
  .container-md {
    max-width: 768px;
  }
}
@media (min-width: 1024px) {
  .container-lg {
    max-width: 1024px;
  }
}
.btn {
  font-weight: 700;
}

@use "sass:map";
@use "sass:meta";

$tones: (
  "success": #2f9e64,
  "warning": #e6a700,
  "danger": #d64550,
);

@each $name, $color in $tones {
  .badge-#{$name} {
    background: $color;
    color: #fff;
  }

  .text-#{$name} {
    color: $color;
  }
}

.quote-keys {
  --ok: #{meta.inspect(map.get(("red": #c00, "blue": #00c), "red"))};
}

.badge-success {
  background: #2f9e64;
  color: #fff;
}

.text-success {
  color: #2f9e64;
}

.badge-warning {
  background: #e6a700;
  color: #fff;
}

.text-warning {
  color: #e6a700;
}

.badge-danger {
  background: #d64550;
  color: #fff;
}

.text-danger {
  color: #d64550;
}

.quote-keys {
  --ok: #c00;
}

🚀 Real-World Use Cases

• Design tokens — colors, weights, radii, z-index layers.
• Breakpoints — named widths that drive media queries.
• Icon fonts — name → glyph maps.
• Theme config — merge defaults with overrides.
• Component APIs — look up options with map.get.

⚠️ Common Pitfalls

• Unquoted color-like keys — red is a color, not the string "red".
• Expecting mutation — map.set returns a new map.
• Putting a map in a CSS property — maps are not valid CSS values.
• Forgetting parentheses — maps must be wrapped in ().
• Ignoring null from map.get — missing keys are falsey; handle them.

💡 Best Practices