Sass map.deep-remove() Function

What You’ll Learn

map.deep-remove() belongs to the built-in sass:map module. It deletes a key at any depth using a key path. This page covers deep vs top-level map.remove, nested cleanup, immutability, Dart Sass 1.27+ support, and five compiled examples.

What Is map.deep-remove()?

Nested config maps often need a single leaf deleted—one weight, one color token—without wiping the parent branch. Official docs: if you pass only $key, you get a copy of $map without that top-level key. If you pass more keys, Sass walks the path and removes the last key from the nested map it finds.

• One key → same idea as removing a top-level entry
• Several keys → walk left to right; delete only the final key
• Parent maps and sibling keys stay intact

📝 Syntax

Load the map module, then call the function:

@use "sass:map";

map.deep-remove($map, $key, $keys...)

Parameters

Return value

📦 Loading sass:map

// Recommended — namespaced
@use "sass:map";
$clean: map.deep-remove($theme, "colors", "accent");

// Optional — bring members into scope
@use "sass:map" as *;
$clean: deep-remove($theme, "colors", "accent");

// Optional — custom namespace
@use "sass:map" as m;
$clean: m.deep-remove($theme, "colors", "accent");

🔍 How the Key Path Works

Official behavior is easy to remember once you split “walk” from “delete”:

• Empty extra keys — copy of $map without $key
• Extra keys present — follow $key plus every key except the last to find a nested map, then remove the last key from that nested map

@use "sass:map";

// Path: Helvetica → weights → (remove) regular
map.deep-remove($fonts, "Helvetica", "weights", "regular");

📋 map.deep-remove vs map.remove

Both return a new map without certain keys. The difference is depth.

@use "sass:map";

$theme: (
  "colors": (
    "primary": #336699,
    "accent": #e67e22,
    "muted": #94a3b8
  ),
  "radius": 8px
);

// Removes only the nested "muted" token
map.deep-remove($theme, "colors", "muted");

// Removes the entire "colors" map (top-level only)
map.remove($theme, "colors");

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS only contains the finished values you read from the cleaned 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";

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

@debug map.deep-remove($font-weights, "regular");

.weights {
  --after: #{meta.inspect(map.deep-remove($font-weights, "regular"))};
}

.weights {
  --after: ("medium": 500, "bold": 700);
}

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

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

@debug map.deep-remove($fonts, "Helvetica", "weights", "regular");

.fonts {
  --after: #{meta.inspect(map.deep-remove($fonts, "Helvetica", "weights", "regular"))};
}

.fonts {
  --after: ("Helvetica": ("weights": ("medium": 500, "bold": 700)));
}

@use "sass:map";

$theme: (
  "colors": (
    "primary": #336699,
    "accent": #e67e22,
    "muted": #94a3b8
  ),
  "radius": 8px
);
$no-accent: map.deep-remove($theme, "colors", "accent");
$no-radius: map.deep-remove($theme, "radius");

.theme {
  --has-accent: #{map.has-key($no-accent, "colors", "accent")};
  --muted: #{map.get($no-accent, "colors", "muted")};
  --has-radius: #{map.has-key($no-radius, "radius")};
  --primary: #{map.get($no-radius, "colors", "primary")};
}

.theme {
  --has-accent: false;
  --muted: #94a3b8;
  --has-radius: false;
  --primary: #336699;
}

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

$font-weights: (
  "regular": 400,
  "medium": 500,
  "bold": 700
);
$same: map.deep-remove($font-weights, "extra-bold");

.miss {
  --same: #{meta.inspect($same)};
}

.miss {
  --same: ("regular": 400, "medium": 500, "bold": 700);
}

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

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

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

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

🚀 Real-World Use Cases

• Theme pruning — drop brand tokens you do not want in a build.
• Optional features — remove nested flags before emitting CSS variables.
• Design-system forks — start from a full map and strip unused branches.
• Mixin APIs — accept a config map, then deep-remove defaults the user disabled.
• Typography scales — delete one weight without rewriting the whole tree (docs sample).

⚠️ Common Pitfalls

• Using map.remove for nested keys — it only touches top-level keys and can delete a whole branch by mistake.
• Forgetting to reassign — deep-remove returns a copy; it does not mutate in place.
• Wrong last key — the final argument is what gets deleted; earlier keys only navigate.
• Old Dart Sass — need 1.27+ for map.deep-remove.
• Expecting a global name — there is no legacy deep-remove() outside sass:map.

💡 Best Practices