Sass map.merge() Function

What You’ll Learn

map.merge() belongs to the built-in sass:map module. It combines two maps into one new map. This page covers overrides, key order, nested path merge, shallow vs map.deep-merge, the legacy map-merge name, and five compiled examples.

What Is map.merge()?

A Sass map is a collection of keys and values—like a small dictionary for design tokens. map.merge() builds a new map that contains every key from both inputs:

• Keys only in $map1 are kept
• Keys only in $map2 are added at the end
• Keys in both maps use the value from $map2

The merge is shallow. If both maps store another map under the same key, $map2’s whole nested map replaces $map1’s. To combine nested maps key-by-key, use map.deep-merge().

📝 Syntax

Load the map module, then call the function:

@use "sass:map";

// Two-argument form (most common)
map.merge($map1, $map2)

// Nested path form (Dart Sass 1.27+)
map.merge($map1, $keys..., $map2)

Parameters

Return value

📦 Loading sass:map

Modern Sass groups map helpers into a module. Load it with @use, then call map.merge. The older global name map-merge still works for two-argument merges.

// Recommended — namespaced
@use "sass:map";
$config: map.merge($base, $overrides);

// Optional — bring members into the current namespace
@use "sass:map" as *;
$config: merge($base, $overrides);

// Optional — custom namespace
@use "sass:map" as m;
$config: m.merge($base, $overrides);

// Legacy global (two maps only)
$config: map-merge($base, $overrides);

🔢 Key Order & Conflicts

Official behavior is predictable once you remember three rules:

@use "sass:map";

$a: ("primary": #336699, "radius": 8px);
$b: ("primary": #1d4ed8, "shadow": true);

map.merge($a, $b);
// ("primary": #1d4ed8, "radius": 8px, "shadow": true)

🔗 Nested Path Merge

With Dart Sass 1.27+, you can pass keys between the two maps. Sass walks those keys to find a nested map, then shallow-merges $map2 into that target. Missing keys along the path become empty maps so the path can be created.

@use "sass:map";

$fonts: (
  "Helvetica": (
    "weights": (
      "lightest": 100,
      "light": 300
    )
  )
);
$heavy-weights: ("medium": 500, "bold": 700);

map.merge($fonts, "Helvetica", "weights", $heavy-weights);
// Helvetica → weights now has lightest, light, medium, and bold

📋 map.merge vs map.deep-merge

Same top-level idea; different treatment of nested maps. The official Helvetica sample shows the trap clearly.

🛠 Compatibility

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

Prefer Dart Sass for new work. Use current Dart Sass (1.27+) if you need nested path merge or map.deep-merge.

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";

$light-weights: ("lightest": 100, "light": 300);
$heavy-weights: ("medium": 500, "bold": 700);

@debug map.merge($light-weights, $heavy-weights);
// ("lightest": 100, "light": 300, "medium": 500, "bold": 700)

.weights {
  --merged: #{meta.inspect(map.merge($light-weights, $heavy-weights))};
}

.weights {
  --merged: ("lightest": 100, "light": 300, "medium": 500, "bold": 700);
}

@use "sass:map";

$base: (
  "primary": #336699,
  "radius": 8px,
  "gap": 16px
);
$brand: (
  "primary": #1d4ed8,
  "accent": #e67e22
);
$theme: map.merge($base, $brand);

.btn {
  color: map.get($theme, "primary");
  border-radius: map.get($theme, "radius");
  gap: map.get($theme, "gap");
  outline-color: map.get($theme, "accent");
}

.btn {
  color: #1d4ed8;
  border-radius: 8px;
  gap: 16px;
  outline-color: #e67e22;
}

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

$fonts: (
  "Helvetica": (
    "weights": (
      "lightest": 100,
      "light": 300
    )
  )
);
$heavy-weights: ("medium": 500, "bold": 700);
$merged: map.merge($fonts, "Helvetica", "weights", $heavy-weights);

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

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

@use "sass:map";

$config: (
  "space": 1rem,
  "line": 1.5
);
$overrides: (
  "space": 1.25rem,
  "max": 72ch
);

$config: map.merge($config, $overrides);

.prose {
  padding: map.get($config, "space");
  line-height: map.get($config, "line");
  max-width: map.get($config, "max");
}

.prose {
  padding: 1.25rem;
  line-height: 1.5;
  max-width: 72ch;
}

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

$helvetica-light: (
  "weights": (
    "lightest": 100,
    "light": 300
  )
);
$helvetica-heavy: (
  "weights": (
    "medium": 500,
    "bold": 700
  )
);

.compare {
  --shallow: #{meta.inspect(map.merge($helvetica-light, $helvetica-heavy))};
  --deep: #{meta.inspect(map.deep-merge($helvetica-light, $helvetica-heavy))};
}

.compare {
  --shallow: ("weights": ("medium": 500, "bold": 700));
  --deep: ("weights": ("lightest": 100, "light": 300, "medium": 500, "bold": 700));
}

🚀 Real-World Use Cases

• Flat design tokens — merge brand colors onto a default palette.
• Component defaults — accept a user options map and overlay it on safe defaults.
• Build-time themes — combine shared and per-page token maps before emitting CSS variables.
• Targeted nested updates — path merge into one branch without rewriting the whole tree.
• Legacy migrations — replace map-merge with namespaced map.merge.

⚠️ Common Pitfalls

• Expecting deep merge — nested colliding maps are replaced, not combined. Use map.deep-merge when siblings must survive.
• Forgetting to reassign — map.merge returns a copy; originals stay unchanged unless you assign the result.
• Wrong overlay order — put defaults first and overrides second so $map2 wins.
• Nested path on old Sass — more than two arguments needs Dart Sass 1.27+.
• Forgetting @use — map.merge is undefined until you load sass:map (or use legacy map-merge).

💡 Best Practices