Sass map.deep-remove()

Beginner
10 min read
Updated: Nov 2026
5 examples
Dart Sass 1.27+
Sass map.deep-remove deleting nested map keys by path
Definition

Definition and Usage

map.deep-remove($map, $key, $keys...) returns a new map without the targeted key. With only $key, it drops a top-level entry. With extra $keys, it walks nested maps and removes the last key in the path. Load it with @use "sass:map" on Dart Sass 1.27+. There is no separate global deep-remove().

Official samples.

Flat: map.deep-remove(("regular": 400, "medium": 500, "bold": 700), "regular") → ("medium": 500, "bold": 700). Nested: pass "Helvetica", "weights", "regular" to drop only that weight.

Path = walk then delete.

Keys before the last one locate the nested map. The last key is the entry that gets removed.

Immutable result.

Original maps stay unchanged. Reassign when you want to keep the cleanup: $theme: map.deep-remove($theme, colors, accent);

Syntax

Syntax

SCSS
@use "sass:map";

// Top-level key
map.deep-remove($map, $key);

// Nested path — last key is removed
map.deep-remove($map, $key, $keys...);

map.deep-remove($fonts, "Helvetica", "weights", "regular");
// removes only "regular" inside Helvetica → weights

Pattern: locate with a key path → map.deep-remove → confirm with map.has-key or map.get.

Reference

Path Rules

Choose the helper based on how deep the key lives:

GoalUse
Drop one nested leafmap.deep-remove($map, $k1, $k2, $leaf)
Drop a whole nested branchmap.deep-remove($map, $parent, $branch)
Drop one or more top-level keysmap.remove($map, $keys...)
Single top-level keyEither deep-remove or remove
Missing leaf keySafe — returns an equivalent copy
Global deep-remove()Not provided — module only
vs map.remove.

map.remove only touches top-level keys. To delete colors.accent without wiping colors, you need map.deep-remove.

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 — Remove a Top-Level Key (Official Docs)

One key argument deletes a flat map entry.

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

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

.flat {
  --result: #{meta.inspect($trimmed)};
  --has-regular: #{map.has-key($trimmed, "regular")};
  --medium: #{map.get($trimmed, "medium")};
}

How It Works

  1. "regular" is removed from the copy.
  2. Other keys remain in order.
  3. Original $font-weights is unchanged.
  4. Matches the official Sass docs sample.

Example 2 — Nested Key Path (Official Docs)

Walk into Helvetica → weights, then drop regular.

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

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

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

.nested {
  --has-regular: #{map.has-key($trimmed, "Helvetica", "weights", "regular")};
  --medium: #{map.get($trimmed, "Helvetica", "weights", "medium")};
  --count: #{list.length(map.keys(map.get($trimmed, "Helvetica", "weights")))};
}

How It Works

  1. First keys locate the nested weights map.
  2. Last key "regular" is the one removed.
  3. medium and bold stay intact.
  4. Matches the official nested-path sample.

Example 3 — deep-remove vs remove

Top-level remove deletes the whole nested branch.

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

$theme: (
  colors: (primary: navy, accent: teal),
  space: (sm: 8px, md: 16px)
);

$deep: map.deep-remove($theme, colors, accent);
$top: map.remove($theme, colors);

.compare {
  --deep-has-accent: #{map.has-key($deep, colors, accent)};
  --deep-primary: #{map.get($deep, colors, primary)};
  --top-has-colors: #{map.has-key($top, colors)};
  --top: #{meta.inspect($top)};
}

How It Works

  1. Deep-remove drops only accent.
  2. primary survives inside colors.
  3. map.remove($theme, colors) deletes the entire colors map.
  4. Pick deep-remove for surgical nested cleanup.

Example 4 — Theme Token Cleanup

Strip optional tokens without rebuilding the whole map.

SCSS
@use "sass:map";

$theme: (
  colors: (primary: navy, accent: teal, muted: gray),
  space: (sm: 8px, md: 16px)
);

$clean: map.deep-remove($theme, colors, accent);

.theme {
  --has-accent: #{map.has-key($clean, colors, accent)};
  --primary: #{map.get($clean, colors, primary)};
  --muted: #{map.get($clean, colors, muted)};
  --sm: #{map.get($clean, space, sm)};
}

How It Works

  1. Accent token is removed from colors.
  2. Sibling tokens stay available.
  3. Other branches like space are untouched.
  4. Useful when a project opts out of optional theme keys.

Example 5 — Reassign After Cleanup

Persist the trimmed map for later reads.

SCSS
@use "sass:map";

$theme: (
  colors: (primary: navy, accent: teal, muted: gray)
);

$theme: map.deep-remove($theme, colors, muted);

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

How It Works

  1. Reassignment stores the cleaned map in $theme.
  2. muted is gone for later rules.
  3. Other color keys remain.
  4. Pair with deep-merge when overrides and removals both apply.

Edge Cases & Pitfalls

Most deep-remove bugs are using map.remove on a nested key, or forgetting to reassign.

path

Last key is the target

Earlier keys only navigate. map.deep-remove($m, a, b, c) removes c inside a → b.

branch

Removing a nested map key

map.deep-remove($fonts, "Helvetica", "weights") drops the whole weights branch, leaving an empty Helvetica map.

assign

Returns a copy

Callers must reassign: $map: map.deep-remove($map, $path...);

module

No global deep-remove()

Always load sass:map and call map.deep-remove.

Toolchain

Sass Support

Prefer the module form with Dart Sass 1.27+. There is no global deep-remove().

APIStatus
map.deep-remove()Dart Sass 1.27+ via @use "sass:map"
Global deep-remove()Not provided
Return typeNew map (input unchanged)
LibSass / Ruby SassNo map.deep-remove

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Removes by key path without rebuilding the whole map.
  • Last key is deleted; earlier keys only navigate.
  • Deeper than map.remove — keeps sibling nested keys.
  • Module only — Dart Sass 1.27+, no global helper.

One line: when a nested token must go, call map.deep-remove($map, $path..., $leaf).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:map"
2. Use deep-remove for nested leaves; remove for top-level keys
3. Remember: last key in the path is deleted
4. Reassign: $map: map.deep-remove($map, ...)
5. Confirm with map.has-key / map.get

Frequently Asked Questions

map.deep-remove($map, $key, $keys...) returns a new map without the targeted key. With only $key it removes a top-level entry. With extra $keys it walks nested maps and removes the last key in the path.
map.remove deletes one or more top-level keys only. map.deep-remove can dig into nested maps using a key path, so you can drop colors.accent without deleting the whole colors map.
Removing a missing leaf key is safe: you get a copy that still looks like the original map for that path.
No. It returns a new map. Reassign if you need to keep the result: $theme: map.deep-remove($theme, colors, accent).
No. Use map.deep-remove() after @use "sass:map" (or @use "sass:map" as * and call deep-remove()).
Dart Sass 1.27+. LibSass and Ruby Sass do not provide this deep helper—prefer current Dart Sass.

Next: Sass map.get()

Read a value from a map—including nested key paths.

map.get() →

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.deep-merge Function Sass map.get Function