Skip to content
Tutorials Center
My learning

Topics

Lesson 18 of 39 ยท Control Directives and Maps

Sass Maps and the sass:map Module

Store design tokens in Sass maps: syntax, map.get, has-key, merge and set, nested maps, iterating with @each and a breakpoint lookup that fails with a clear error.

A map is a collection of key/value pairs, like an object in JavaScript or a dictionary in Python. In Sass it is the natural home for design tokens: named colors, spacing steps, breakpoints, font sizes. Instead of a pile of loose variables ($color-primary, $color-danger, $color-success...) you keep one structured value and ask it questions.

Creating a map

A map is written as parenthesized key: value pairs separated by commas:

SCSS
$breakpoints: (
  "sm": 576px,
  "md": 768px,
  "lg": 992px,
  "xl": 1200px
);

Keys can be any value, but quoted strings are the safe, common choice (they avoid confusion with color names such as red). A trailing comma after the last pair is allowed and makes diffs tidy. A map with no pairs is (), which is also the empty list.

Reading values: map.get

Load the module first and use map.get:

SCSS
@use "sass:map";

.container { max-width: map.get($breakpoints, "lg"); }   // 992px

If the key does not exist, map.get returns null (and the declaration disappears). That silence can hide typos, so in your own helpers check first, as shown below.

The sass:map functions

Function Purpose
map.get($m, $key) Value for a key, or null
map.has-key($m, $key) Is the key present?
map.keys($m) / map.values($m) Lists of keys or values
map.merge($a, $b) Combine maps; $b wins on conflicts
map.remove($m, $keys...) A copy without the given keys
map.set($m, $key, $value) A copy with one key set
map.deep-merge($a, $b) Merge nested maps recursively
map.deep-remove($m, $keys...) Remove a key at a nested path

Remember that Sass values are immutable: map.merge and map.set return a new map, so assign the result.

SCSS
$tokens: (spacing: 8px);
$tokens: map.merge($tokens, (radius: 6px));   // spacing and radius
Map functions

Notice that missing: map.get(...) is not printed at all: null drops the declaration. A map itself cannot be a CSS value, so the demo wraps maps in meta.inspect() to print them as text.

Nested maps

Values can be maps, so one variable can hold a whole theme:

SCSS
$theme: (
  "colors": (
    "primary": #0ea5e9,
    "danger": #dc2626
  ),
  "spacing": (
    "sm": 8px,
    "md": 16px
  )
);

.card {
  color: map.get($theme, "colors", "primary");   // nested lookup
  padding: map.get($theme, "spacing", "md");
}

map.get accepts several keys in a row to walk down the levels, and map.set($theme, "colors", "primary", #7c3aed) updates a nested value. map.deep-merge combines two themes, which is how a dark theme overrides only the colors it changes while inheriting the rest.

Looping over a map

Combine maps with @each (see Each, for and while):

SCSS
@each $name, $value in map.get($theme, "colors") {
  .text-#{$name} { color: $value; }
}

For a nested map, loop over the outer map first and inside it over each inner map.

A safe lookup function

Because map.get quietly returns null, wrap it in a function that fails loudly when a key is missing. Errors at compile time are much easier to fix than a missing style discovered in production:

SCSS
@use "sass:map";

$breakpoints: ("sm": 576px, "md": 768px, "lg": 992px);

@function bp($name) {
  @if not map.has-key($breakpoints, $name) {
    @error "Unknown breakpoint `#{$name}`. Use one of: #{map.keys($breakpoints)}.";
  }
  @return map.get($breakpoints, $name);
}

@mixin from($name) {
  @media (min-width: bp($name)) { @content; }
}

.nav { @include from("md") { display: flex; } }
A named breakpoint mixin with a safe lookup

Keyword arguments and maps

A map can be spread into keyword arguments, so a mixin call can be driven by data:

SCSS
@mixin button($bg, $color: white, $radius: 6px) { /* ... */ }

$primary-button: (bg: #0ea5e9, radius: 99px);
.btn { @include button($primary-button...); }

This works because map keys become argument names (unquoted symbols such as bg). Quoted keys such as "bg" also work in current Sass, but identifier keys are more common for this use.

Tips for token maps

  • Group tokens by purpose (colors, spacing, type), each in its own map.
  • Keep keys in kebab-case so that they translate into class names and custom properties.
  • Export to CSS variables with a loop, so the browser can use the same tokens (shown in Design tokens and theming).
  • Use @error in lookup functions; avoid silent nulls.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does map.get($map, "nope") return when the key does not exist?

    map.get returns null, so a declaration using it disappears silently. Wrap lookups in a function that raises @error.
  2. 2. Which line adds a key and keeps the original map unchanged?

    Maps are immutable. merge (or set) returns a new map that you assign.
  3. 3. How do you read a value two levels deep?

    map.get accepts several keys in a row to walk into nested maps.
  4. 4. What does the empty parentheses () represent?

    An empty pair of parentheses is both an empty list and an empty map.

Summary

  • A map is (key: value, ...); read with map.get, test with map.has-key, change by creating new maps with merge, set and remove.
  • Nested maps hold themes; map.get accepts several keys, and map.deep-merge combines themes.
  • @each $key, $value in $map generates rules from tokens.
  • Wrap lookups in functions that @error on unknown keys.
  • Maps can be spread into keyword arguments.

Next: Building spacing, color and type scales