Sass Maps

What Is a Sass Map?

A map associates keys with values, written as (key: value, key: value). Maps are commonly used to represent structured configuration, like breakpoints, a spacing scale, or a full color palette, in one central, named place.

@use 'sass:map';

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

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

map.get() looks up a value by key, exactly like reading a property from an object in most programming languages.

Map Syntax and Access

$map: (key1: value1, key2: value2);
map.get($map, key1);
map.has-key($map, key1);
map.keys($map);
map.values($map);

• Maps always use parentheses with comma-separated key: value pairs.
• map.get() retrieves a value by key, returning null if the key doesn't exist.
• map.has-key() checks whether a key exists before you try to use its value.
• map.keys() and map.values() return the map's keys or values as separate lists.

Sass Maps Cheatsheet

The sass:map module functions you'll use to build design tokens and configuration.

Reading and Checking Map Values

Always check for a key's existence with map.has-key() before assuming map.get() returned a meaningful value, since a missing key silently returns null rather than raising an error.

@use 'sass:map';

$sizes: (sm: 8px, md: 16px, lg: 24px);

@function get-size($key) {
  @if not map.has-key($sizes, $key) {
    @error "Unknown size key: #{$key}";
  }
  @return map.get($sizes, $key);
}

Merging and Updating Maps

map.merge() combines two maps into a new one, with the second map's values winning on any overlapping keys, a common pattern for layering a user's custom configuration on top of a library's defaults.

$default-theme: (primary: #2563eb, radius: 4px);
$custom-theme: (radius: 12px);

$final-theme: map.merge($default-theme, $custom-theme);
// => (primary: #2563eb, radius: 12px)

Iterating a Map With @each

@each can destructure a map's entries directly into a key and value variable, making it easy to generate a rule for every entry, exactly as shown in the Colors lesson's palette example.

$spacers: (sm: 8px, md: 16px, lg: 24px);

@each $name, $value in $spacers {
  .p-#{$name} {
    padding: $value;
  }
}

Generates .p-sm, .p-md, and .p-lg, one rule per map entry.

Common Mistakes

• Calling map.get() on a missing key and using the resulting null value without checking it first, producing a broken declaration.
• Forgetting that map keys must be unique; duplicate keys in a map literal silently keep only the last one.
• Using map.merge() in the wrong argument order, overwriting the values you actually meant to keep.
• Building deeply nested maps (maps of maps of maps) that become hard to read and query without small helper functions.

Key Takeaways

• Sass maps store key-value pairs using (key: value, ...) syntax.
• map.get(), map.has-key(), map.keys(), and map.values() cover most map reading needs.
• map.merge() layers one map's values on top of another, ideal for configurable defaults.
• @each $key, $value in $map is the standard way to iterate over a map's entries.