Sass map.set() Function

What You’ll Learn

map.set() belongs to the built-in sass:map module. It returns a new map with one key written (added or updated). This page covers nested path updates, missing path segments, immutability, vs map.merge, and five compiled examples.

What Is map.set()?

Sass maps are immutable. You cannot assign into a map like $map["primary"] = #fff. Instead, map.set() builds a new map with one key written:

• If the key is new, it is added
• If the key already exists, its value is replaced
• All other keys are copied as they were

With Dart Sass 1.27+, you can pass a path of keys to update a nested value without rebuilding the whole tree by hand.

📝 Syntax

Load the map module, then call the function:

@use "sass:map";

// Top-level key
map.set($map, $key, $value)

// Nested path (Dart Sass 1.27+)
map.set($map, $keys..., $key, $value)

Parameters

Return value

📦 Loading sass:map

map.set lives in the map module. There is no legacy global map-set()—always load sass:map.

// Recommended — namespaced
@use "sass:map";
$tokens: map.set($tokens, "primary", #1d4ed8);

// Optional — bring members into the current namespace
@use "sass:map" as *;
$tokens: set($tokens, "primary", #1d4ed8);

// Optional — custom namespace
@use "sass:map" as m;
$tokens: m.set($tokens, "primary", #1d4ed8);

🔢 Add vs Update

The same call handles both cases. Sass does not care whether the key already existed.

@use "sass:map";

$weights: ("regular": 400, "bold": 700);

// Update an existing key
map.set($weights, "regular", 300);
// ("regular": 300, "bold": 700)

// Add a new key
map.set($weights, "medium", 500);
// ("regular": 400, "bold": 700, "medium": 500)

🔗 Nested Path Set

With Dart Sass 1.27+, pass keys before the final key/value to update a nested map. If a key along the path is missing or not a map, Sass stores an empty map there so the path can continue.

@use "sass:map";

$fonts: (
  "Helvetica": (
    "weights": (
      "regular": 400,
      "medium": 500,
      "bold": 700
    )
  )
);

map.set($fonts, "Helvetica", "weights", "regular", 300);
// Helvetica → weights → regular is now 300

📋 map.set vs map.merge

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS only contains the finished values you read from the updated map (for example with map.get).

Prefer Dart Sass for new work. Use current Dart Sass (1.27+) for nested path updates.

Examples Gallery

Each example uses @use "sass:map". Open View Compiled CSS to see what Dart Sass emits (maps inspected via meta.inspect where needed).

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

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

@debug map.set($font-weights, "regular", 300);
// ("regular": 300, "medium": 500, "bold": 700)

.weights {
  --updated: #{meta.inspect(map.set($font-weights, "regular", 300))};
}

.weights {
  --updated: ("regular": 300, "medium": 500, "bold": 700);
}

@use "sass:map";

$palette: (
  "primary": #336699,
  "muted": #94a3b8
);
$palette: map.set($palette, "accent", #e67e22);

.btn {
  color: map.get($palette, "primary");
  outline-color: map.get($palette, "accent");
}

.btn {
  color: #336699;
  outline-color: #e67e22;
}

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

$fonts: (
  "Helvetica": (
    "weights": (
      "regular": 400,
      "medium": 500,
      "bold": 700
    )
  )
);
$updated: map.set($fonts, "Helvetica", "weights", "regular", 300);

.font {
  --regular: #{map.get($updated, "Helvetica", "weights", "regular")};
  --weights: #{meta.inspect(map.get($updated, "Helvetica", "weights"))};
}

.font {
  --regular: 300;
  --weights: ("regular": 300, "medium": 500, "bold": 700);
}

@use "sass:map";

$theme: (
  "primary": #336699,
  "radius": 8px,
  "gap": 16px
);
$theme: map.set($theme, "primary", #1d4ed8);

.card {
  --primary: #{map.get($theme, "primary")};
  --radius: #{map.get($theme, "radius")};
  --gap: #{map.get($theme, "gap")};
}

.card {
  --primary: #1d4ed8;
  --radius: 8px;
  --gap: 16px;
}

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

$config: ("meta": ("name": "app"));
$built: map.set($config, "theme", "colors", "primary", #1d4ed8);

.demo {
  --built: #{meta.inspect($built)};
  --primary: #{map.get($built, "theme", "colors", "primary")};
}

.demo {
  --built: ("meta": ("name": "app"), "theme": ("colors": ("primary": #1d4ed8)));
  --primary: #1d4ed8;
}

🚀 Real-World Use Cases

• Single token patches — change one color, radius, or weight without rebuilding the map.
• Nested design systems — update brand → colors → primary with a path set.
• Mixin APIs — accept a user key/value and write it onto defaults.
• Incremental builders — grow a config map step by step during compilation.
• Safe path creation — let missing segments become empty maps when scaffolding tokens.

⚠️ Common Pitfalls

• Forgetting to reassign — map.set returns a copy; originals stay unless you assign the result.
• Wrong argument order — the last argument is always the value; the one before it is the key being set.
• Expecting a global map-set — there is none; load sass:map.
• Nested path on old Sass — more than three arguments needs Dart Sass 1.27+.
• Using set for many keys — prefer map.merge when overlaying a whole map of updates.

💡 Best Practices