Sass map.remove() Function

What You’ll Learn

map.remove() belongs to the built-in sass:map module. It returns a new map with one or more top-level keys deleted. This page covers multi-key removal, missing keys, immutability, vs map.deep-remove, the legacy map-remove name, and five compiled examples.

What Is map.remove()?

Design token maps grow over time. Sometimes you need a copy without a legacy flag, a deprecated color, or a weight you no longer ship. map.remove() does exactly that for top-level keys:

• Pass the map, then every key you want gone
• Get a new map back—the original stays unchanged
• Keys that were never there are simply ignored

It does not walk into nested maps. To delete fonts → Helvetica → weights → regular, use map.deep-remove().

📝 Syntax

Load the map module, then call the function:

@use "sass:map";

map.remove($map, $keys...)

Parameters

*You normally pass at least one key. Passing none returns a copy of the map unchanged.

Return value

📦 Loading sass:map

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

// Recommended — namespaced
@use "sass:map";
$clean: map.remove($tokens, "legacy");

// Optional — bring members into the current namespace
@use "sass:map" as *;
$clean: remove($tokens, "legacy");

// Optional — custom namespace
@use "sass:map" as m;
$clean: m.remove($tokens, "legacy");

// Legacy global
$clean: map-remove($tokens, "legacy");

🔍 How Removal Works

Official behavior is easy to remember:

• Only top-level keys are candidates for deletion
• You can list many keys in one call
• Unknown keys do not cause an error
• Remaining keys keep their relative order

@use "sass:map";

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

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

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

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

📋 map.remove vs map.deep-remove

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

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

Prefer Dart Sass for new work. Use map.deep-remove on Dart Sass 1.27+ when you need nested key paths.

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

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

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

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

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

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

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

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

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

.weights {
  --medium-only: ("medium": 500);
}

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

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

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

.safe {
  --all: #{meta.inspect(map.remove($font-weights, "bolder"))};
  --partial: #{meta.inspect(map.remove($font-weights, "regular", "bolder"))};
}

.safe {
  --all: ("regular": 400, "medium": 500, "bold": 700);
  --partial: ("medium": 500, "bold": 700);
}

@use "sass:map";

$theme: (
  "primary": #1d4ed8,
  "muted": #94a3b8,
  "_debug": true,
  "_draft": "v2"
);

$public: map.remove($theme, "_debug", "_draft");

.theme {
  --primary: #{map.get($public, "primary")};
  --muted: #{map.get($public, "muted")};
}

.theme {
  --primary: #1d4ed8;
  --muted: #94a3b8;
}

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

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

.compare {
  --top-level: #{meta.inspect(map.remove($fonts, "weights"))};
  --nested-leaf: #{meta.inspect(map.deep-remove($fonts, "weights", "regular"))};
}

.compare {
  --top-level: ("family": "Helvetica");
  --nested-leaf: ("weights": ("medium": 500, "bold": 700), "family": "Helvetica");
}

🚀 Real-World Use Cases

• Strip internal flags — remove _debug / draft keys before emitting CSS variables.
• Legacy cleanup — drop deprecated tokens from a shared palette map.
• Feature subsets — build a lighter token map for a component package.
• Safe optional deletes — list keys that might not exist; missing ones are ignored.
• Flat maps only — pair with map.deep-remove when nesting is involved.

⚠️ Common Pitfalls

• Expecting nested deletes — map.remove($map, "colors", "accent") treats both as top-level keys to delete, not a path. Use map.deep-remove for paths.
• Forgetting to reassign — remove returns a copy; originals stay unless you assign the result.
• Deleting a whole branch by mistake — removing a nested map’s parent key drops every child token.
• Assuming missing keys error — they are ignored; double-check spellings if nothing changed.
• Forgetting @use — map.remove needs sass:map (or use legacy map-remove).

💡 Best Practices