Sass map.set()

Beginner
10 min read
Updated: Nov 2026
5 examples
Dart Sass 1.27+
Sass map.set adding or updating a map key or nested path
Definition

Definition and Usage

map.set($map, $key, $value) returns a new map with $key set to $value (add or replace). With extra keys—map.set($map, $keys..., $key, $value)—it walks a nested path and sets the final key. Load it with @use "sass:map" on Dart Sass 1.27+ for nested paths (module API overall needs 1.23+). There is no global map-set().

Official samples.

Flat: map.set(("regular": 400, "medium": 500, "bold": 700), "regular", 300) → ("regular": 300, "medium": 500, "bold": 700). Nested: map.set($fonts, "Helvetica", "weights", "regular", 300).

Missing path → empty maps.

Official docs: if a mid-path key is missing or not a map, Sass sets that key to an empty map so the write can continue.

Immutable result.

Original maps stay unchanged. Reassign when you want to keep the write: $tokens: map.set($tokens, "primary", navy);

Syntax

Syntax

SCSS
@use "sass:map";

map.set($map, $key, $value);
map.set($map, $keys..., $key, $value); // nested path (Dart Sass)

map.set($font-weights, "regular", 300);
map.set($fonts, "Helvetica", "weights", "regular", 300);

// Module only — no global map-set()

Pattern: write with map.set → read with map.get → for many keys at once prefer map.merge or map.deep-merge.

Reference

Flat vs Nested

Use one key for top-level writes; pass a path for nested tokens:

GoalUse
Add / update one top-level keymap.set($map, $key, $value)
Update a nested leafmap.set($map, $k1, $k2, $leaf, $value)
Create a nested path from scratchSame nested form — missing keys become empty maps
Overlay many keysmap.merge / map.deep-merge
Delete a keymap.remove / map.deep-remove
Global map-set()Not provided — module only
Argument shape.

Official docs describe nested calls as $map, $keys..., $key, $value. In practice you pass one argument list: path keys, then the final key, then the value.

Code

SCSS Examples

Examples target Dart Sass 1.27+ with @use "sass:map". Open View Compiled CSS for verified output (matches official Sass docs samples).

Example 1 — Update a Top-Level Key (Official Docs)

Replace an existing weight without mutating the original map.

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

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

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

How It Works

  1. regular becomes 300 in the copy.
  2. Other keys stay the same.
  3. Original map still has 400.
  4. Matches the official Sass docs sample.

Example 2 — Nested Path Update (Official Docs)

Walk into Helvetica → weights, then set regular.

SCSS
@use "sass:map";

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

$updated: map.set($fonts, "Helvetica", "weights", "regular", 300);

.nested {
  --regular: #{map.get($updated, "Helvetica", "weights", "regular")};
  --medium: #{map.get($updated, "Helvetica", "weights", "medium")};
}

How It Works

  1. Path keys locate the nested weights map.
  2. Last key + value perform the write.
  3. Sibling keys like medium stay intact.
  4. Matches the official nested-path sample.

Example 3 — Add a New Key

If the key does not exist, it is appended.

SCSS
@use "sass:map";

$font-weights: ("regular": 400, "medium": 500, "bold": 700);
$extended: map.set($font-weights, "black", 900);

.add {
  --black: #{map.get($extended, "black")};
  --has: #{map.has-key($extended, "black")};
}

How It Works

  1. black did not exist before.
  2. Set creates the key with value 900.
  3. has-key confirms presence.
  4. Same helper handles both add and update.

Example 4 — Create a Nested Path

Missing mid-path keys become empty maps, then the leaf is set.

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

$new: map.set((), "button", "pad", 8px);

.path {
  --result: #{meta.inspect($new)};
  --pad: #{map.get($new, "button", "pad")};
}

How It Works

  1. Start from () — an empty map.
  2. button is created as a nested map.
  3. pad is set to 8px.
  4. Handy when building config trees incrementally.

Example 5 — Reassign a Theme Token

Persist a nested update for later CSS reads.

SCSS
@use "sass:map";

$config: (button: (pad: 8px, radius: 2px));
$config: map.set($config, button, radius, 6px);

.btn {
  padding: map.get($config, button, pad);
  border-radius: map.get($config, button, radius);
}

How It Works

  1. Reassignment keeps the updated map in $config.
  2. radius becomes 6px.
  3. pad is unchanged.
  4. Prefer set for one-token writes; merge for bulk overlays.

Edge Cases & Pitfalls

Most map.set bugs are forgetting to reassign, or overwriting a nested map with a non-map mid-path.

assign

Returns a copy

Callers must reassign: $map: map.set($map, $key, $value);

path

Non-map mid-path is replaced

If a path key holds a color or number, Sass replaces it with an empty map so the nested set can proceed—that can drop the old value.

bulk

One key at a time

For many updates, map.merge / deep-merge is clearer than chained map.set calls.

module

No global map-set()

Always load sass:map and call map.set.

Toolchain

Sass Support

Prefer the module form. Nested multi-key set needs Dart Sass 1.27+. There is no global map-set().

APIStatus
map.set($map, $key, $value)Dart Sass via @use "sass:map"
Nested path setDart Sass 1.27+
Global map-set()Not provided
Return typeNew map (input unchanged)

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Adds or updates one key and returns a new map.
  • Nested paths write deep tokens without rebuilding the whole tree.
  • Use merge for bulk overlays; set for single writes.
  • Module only — no global map-set().

One line: when one map key must change, call map.set($map, $key, $value) or map.set($map, $path..., $value).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:map"
2. Use map.set for single key / nested leaf writes
3. Use merge / deep-merge for many keys
4. Reassign: $map: map.set($map, ...)
5. Confirm with map.get / map.has-key

Frequently Asked Questions

map.set($map, $key, $value) returns a new map with $key set to $value. If the key already exists, its value is replaced. Extra keys before the final key/value (Dart Sass) update a nested map along that path.
No. It returns a copy. Reassign if you need to keep the result: $tokens: map.set($tokens, "primary", #1d4ed8).
Yes on Dart Sass: map.set($map, "a", "b", "c", $value) walks a → b and sets c to $value. Missing keys along the path become empty maps.
map.set updates one key (or one nested leaf). map.merge combines two whole maps. Use set for a single write; use merge when overlaying many keys at once.
No. Unlike map-get or map-remove, map.set is module-only. Load it with @use "sass:map" (or @use "sass:map" as * and call set()).
Official docs: if any key in the path is missing or points to a non-map, Sass sets that key to an empty map so the path can continue, then applies the final set.

Next: Sass map.values()

Get a comma-separated list of every value in a map.

map.values() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

Sass map.remove Function Sass map.values Function