Sass map.deep-merge() Function

What You’ll Learn

map.deep-merge() belongs to the built-in sass:map module. It merges two maps and recursively merges nested maps. This page covers deep vs shallow map.merge, theme overrides, immutability, Dart Sass 1.27+ support, and five compiled examples.

What Is map.deep-merge()?

Design systems often store config as nested maps—fonts, colors, breakpoints. You want a base map plus overrides without wiping an entire nested branch. Official docs: map.deep-merge is identical to map.merge, except nested map values are also recursively merged.

• Both maps keep top-level keys that do not collide
• When both have a map at the same key, those maps are merged together
• When values are not both maps, $map2’s value replaces $map1’s

📝 Syntax

Load the map module, then call the function:

@use "sass:map";

map.deep-merge($map1, $map2)

Parameters

Return value

📦 Loading sass:map

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

// Optional — bring members into scope
@use "sass:map" as *;
$config: deep-merge($base, $overrides);

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

🔍 map.deep-merge vs map.merge

This is the key beginner trap. Official Helvetica weights sample shows it clearly.

@use "sass:map";

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

// deep-merge keeps all four weight keys
map.deep-merge($helvetica-light, $helvetica-heavy);

// merge replaces the whole "weights" map with $helvetica-heavy’s only
map.merge($helvetica-light, $helvetica-heavy);

📋 When Values Are Not Both Maps

Recursion only happens when both sides store a map at that key. If $map2 puts a color, number, or other scalar where $map1 had a map, the scalar wins.

@use "sass:map";

$left: ("token": ("size": 16px));
$right: ("token": 1rem);

map.deep-merge($left, $right);
// ("token": 1rem) — not a nested merge

🛠 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).

Examples Gallery

Each example uses @use "sass:map". Open View Compiled CSS for verified Dart Sass output (official samples where noted).

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

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

@debug map.deep-merge($helvetica-light, $helvetica-heavy);
@debug map.merge($helvetica-light, $helvetica-heavy);

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

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

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

$base: (
  "colors": (
    "primary": #336699,
    "muted": #94a3b8
  ),
  "radius": 8px
);
$theme: (
  "colors": (
    "accent": #e67e22,
    "primary": #1d4ed8
  ),
  "shadow": 0 4px 12px rgba(0, 0, 0, 0.12)
);
$merged: map.deep-merge($base, $theme);

.theme {
  --primary: #{map.get($merged, "colors", "primary")};
  --accent: #{map.get($merged, "colors", "accent")};
  --muted: #{map.get($merged, "colors", "muted")};
  --radius: #{map.get($merged, "radius")};
  --shadow: #{meta.inspect(map.get($merged, "shadow"))};
}

.theme {
  --primary: #1d4ed8;
  --accent: #e67e22;
  --muted: #94a3b8;
  --radius: 8px;
  --shadow: 0 4px 12px rgba(0, 0, 0, 0.12);
}

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

$a: ("a": 1, "nested": ("x": 10, "y": 20));
$b: ("b": 2, "nested": ("y": 99, "z": 30));
$c: map.deep-merge($a, $b);

.compare {
  --all: #{meta.inspect($c)};
  --y: #{map.get($c, "nested", "y")};
}

.compare {
  --all: ("a": 1, "nested": ("x": 10, "y": 99, "z": 30), "b": 2);
  --y: 99;
}

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

$orig: ("a": ("b": 1));
$copy: map.deep-merge($orig, ("a": ("c": 2)));

.immut {
  --orig: #{meta.inspect($orig)};
  --copy: #{meta.inspect($copy)};
}

.immut {
  --orig: ("a": ("b": 1));
  --copy: ("a": ("b": 1, "c": 2));
}

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

$left: ("token": ("size": 16px));
$right: ("token": 1rem);
$override: map.deep-merge($left, $right);

.scalar {
  --token: #{meta.inspect(map.get($override, "token"))};
}

.scalar {
  --token: 1rem;
}

🚀 Real-World Use Cases

• Design-system themes — layer brand overrides onto shared defaults.
• Component configs — merge partial option maps without losing siblings.
• Multi-brand builds — deep-merge per-brand token files into one config.
• Plugin / mixin APIs — accept user maps and merge onto safe defaults.
• Nested typography scales — combine weight/size branches like the docs sample.

⚠️ Common Pitfalls

• Using merge by habit — shallow merge drops nested siblings you meant to keep.
• Forgetting to reassign — deep-merge returns a copy; it does not mutate in place.
• Scalar overrides — a non-map in $map2 replaces a whole nested map.
• Old Dart Sass — need 1.27+ for map.deep-merge.
• Expecting a global name — there is no legacy deep-merge() outside sass:map.

💡 Best Practices