Maps hold key/value pairs, written ("key": value, ...). Keys must be unique; values may repeat. Parentheses are required.
Maps never appear directly in CSS. Look values up with map.get() (or loop with @each) and emit normal CSS.
Prefer "red" over bare red—unquoted names can be colors, not strings.
map.set() and map.merge() return new maps. Reassign the variable to keep updates.
@use "sass:map";
$font-weights: (
"regular": 400,
"medium": 500,
"bold": 700,
);
map.get($font-weights, "medium"); // 500
map.get($font-weights, "extra-bold"); // null
map.set($font-weights, "extra-bold", 900); // new map
map.merge($a, $b); // combine maps
@each $key, $value in $font-weights { ... }Pattern: define a map → read with map.get → update with map.set / map.merge → loop pairs with @each.
Everyday map tools:
| Pattern | Result idea |
|---|---|
("a": 1, "b": 2) | Map literal (parentheses required) |
map.get($map, $key) | Value, or null if missing |
map.set($map, $key, $val) | New map with that key set |
map.merge($a, $b) | Combine maps ($b wins on clashes) |
@each $k, $v in $map | Loop every pair |
() | Empty map (also an empty list) |
Open View Compiled CSS for verified Dart Sass output (matches official Sass docs samples where shown).
map.getLook up a key; missing keys return null (falsey).
@use "sass:map";
$font-weights: ("regular": 400, "medium": 500, "bold": 700);
.medium {
font-weight: map.get($font-weights, "medium");
}
.demo {
--has-extra: #{map.has-key($font-weights, "extra-bold")};
}500.null.@each Over a MapAssign each key and value, then emit a rule per pair.
$icons: ("eye": "\f112", "start": "\f12e", "stop": "\f12f");
@each $name, $glyph in $icons {
.icon-#{$name}:before {
display: inline-block;
font-family: "Icon Font";
content: $glyph;
}
}content value.map.set (Immutable)Add or replace a key; the original map stays unchanged.
@use "sass:map";
$font-weights: ("regular": 400, "medium": 500, "bold": 700);
$updated: map.set($font-weights, "extra-bold", 900);
$replaced: map.set($font-weights, "bold", 900);
.demo {
--extra: #{map.get($updated, "extra-bold")};
--bold: #{map.get($replaced, "bold")};
--orig-bold: #{map.get($font-weights, "bold")};
}"extra-bold" on a copy.700.map.mergeCombine maps; the second map wins when keys clash.
@use "sass:map";
$light-weights: ("lightest": 100, "light": 300);
$heavy-weights: ("medium": 500, "bold": 700);
$merged: map.merge($light-weights, $heavy-weights);
$weights: ("light": 300, "medium": 500);
$over: map.merge($weights, ("medium": 700));
.demo {
--lightest: #{map.get($merged, "lightest")};
--bold: #{map.get($merged, "bold")};
--medium: #{map.get($over, "medium")};
}Store design tokens in a map and look them up in rules.
@use "sass:map";
$theme: (
"primary": #036,
"accent": #c6538c,
);
.button {
background: map.get($theme, "primary");
color: white;
&.accent {
background: map.get($theme, "accent");
}
}Most map bugs are unquoted keys or forgetting to reassign after set/merge.
Bare red is a color. Use "red" when you mean a string key.
Check with map.has-key() or test the result in @if.
$map: map.set($map, $k, $v); keeps the new map.
Each pair is a two-element list. Empty () is both an empty map and an empty list. See lists.
Maps and sass:map are core Sass on Dart Sass.
| Feature | Status |
|---|---|
Map literals (...) | Supported |
map.get / set / merge | Supported |
@each over maps | Supported |
| Maps as lists | Supported |
Compile with the Dart Sass CLI.
(...).null.set / merge.One line: keep config in a map, look values up with map.get, and generate CSS with @each.
Practical checklist:
1. Write maps with parentheses and quoted keys
2. Look up values with map.get($map, $key)
3. Loop pairs with @each $key, $value in $map
4. Update with map.set / map.merge (then reassign)
5. Remember maps are not valid CSS by themselvesUse true / false (and map.has-key results) with @if.
8 people found this page helpful