Sass map.remove()

Beginner
10 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass map.remove deleting top-level keys from a map
Definition

Definition and Usage

map.remove($map, $keys...) returns a new map without the listed top-level keys. Missing keys are ignored. Load it with @use "sass:map" on Dart Sass 1.23+. Legacy global name: map-remove.

Official samples.

map.remove(("regular": 400, "medium": 500, "bold": 700), "regular") → ("medium": 500, "bold": 700). Multiple keys: map.remove($map, "regular", "bold") → ("medium": 500).

Top-level only.

To delete colors.accent without wiping colors, use map.deep-remove().

Immutable result.

Original maps stay unchanged. Reassign when you want to keep the cleanup: $tokens: map.remove($tokens, "legacy");

Syntax

Syntax

SCSS
@use "sass:map";

map.remove($map, $keys...); //=> map

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

map.remove($font-weights, "regular", "bold");
// ("medium": 500)

map.remove($font-weights, "bolder");
// unchanged copy — missing key ignored

// Legacy global (prefer module form)
// map-remove($map, $keys...);

Pattern: drop unused top-level tokens with map.remove → confirm with map.has-key or map.keys.

Reference

remove vs deep-remove

Choose based on how deep the key lives:

GoalUse
Drop one top-level keymap.remove($map, $key)
Drop several top-level keysmap.remove($map, $a, $b, $c)
Drop a nested leafmap.deep-remove($map, $path..., $leaf)
Missing keyIgnored — no error
Whole nested branchmap.remove($map, $branch) deletes that top-level entry
Global map-remove()Works; prefer module map.remove
Remaining key order.

Keys that are kept keep their original relative order.

Code

SCSS Examples

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

Example 1 — Remove One Key (Official Docs)

Drop a single top-level entry from a weight map.

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

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

.one {
  --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 map is unchanged.
  4. Matches the official Sass docs sample.

Example 2 — Remove Several Keys (Official Docs)

Pass every key you want dropped in one call.

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

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

.multi {
  --result: #{meta.inspect(map.remove($font-weights, "regular", "bold"))};
}

How It Works

  1. Two keys are removed together.
  2. Only medium remains.
  3. Variadic API avoids chained removes.
  4. Matches the official multi-key sample.

Example 3 — Missing Key Is Ignored (Official Docs)

Unknown keys do not throw.

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

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

.missing {
  --result: #{meta.inspect(map.remove($font-weights, "bolder"))};
}

How It Works

  1. bolder is not in the map.
  2. Result looks unchanged for that key.
  3. Still a new map copy (safe to reassign).
  4. Matches the official missing-key sample.

Example 4 — remove vs deep-remove

Top-level remove deletes a whole nested branch.

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

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

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

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

How It Works

  1. map.remove(..., colors) deletes the entire colors map.
  2. deep-remove drops only accent.
  3. primary survives with deep-remove.
  4. Pick based on depth of the token you want gone.

Example 5 — Reassign After Cleanup

Strip optional top-level groups and keep the trimmed map.

SCSS
@use "sass:map";

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

$theme: map.remove($theme, radius, space);

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

How It Works

  1. Two top-level keys are removed in one call.
  2. Reassignment stores the cleaned map.
  3. colors remains for later reads.
  4. Useful when a project opts out of whole token groups.

Edge Cases & Pitfalls

Most remove bugs are using it for nested leaves, or forgetting to reassign.

nested

Cannot target nested leaves

map.remove($theme, accent) does nothing useful if accent lives under colors. Use deep-remove.

branch

Removing a nested map key

map.remove($theme, colors) deletes the entire colors branch, not one color token.

assign

Returns a copy

Callers must reassign: $map: map.remove($map, $keys...);

legacy

Prefer map.remove over map-remove

Global map-remove still works but is deprecated toward Dart Sass 3.0. Use the module API.

Toolchain

Sass Support

Prefer the module form with a current Dart Sass release.

APIStatus
map.remove()Dart Sass 1.23+ via @use "sass:map"
Global map-remove()Works; deprecated toward Sass 3.0
Return typeNew map (input unchanged)
Missing keysIgnored

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Deletes top-level keys and returns a new map.
  • Variadic — remove several keys in one call.
  • Use deep-remove for nested leaf keys.
  • Prefer map.remove over deprecated global map-remove.

One line: when a top-level map key must go, call map.remove($map, $keys...).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:map"
2. Use remove for top-level keys; deep-remove for nested leaves
3. Pass multiple keys in one call when needed
4. Reassign: $map: map.remove($map, ...)
5. Confirm with map.has-key / map.keys

Frequently Asked Questions

map.remove($map, $keys...) returns a new map without the listed top-level keys. Other keys stay in place. It does not dig into nested maps—use map.deep-remove for nested paths.
No. It returns a copy. Reassign if you need to keep the result: $tokens: map.remove($tokens, "legacy").
Missing keys are ignored. The result is still a valid copy of the map (unchanged for those keys). No error is thrown.
Yes. Pass every key after the map: map.remove($map, "a", "b", "c").
Yes. map-remove($map, $keys...) is the older global name, but Dart Sass deprecates global built-ins toward Sass 3.0. Prefer map.remove after @use "sass:map".
map.remove only deletes top-level keys. map.deep-remove can walk a nested path and delete a leaf key while keeping parent maps and siblings.

Next: Sass map.set()

Set a value at a key—or nested path—and get a new map back.

map.set() →

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