Sass map.has-key() Function

What You’ll Learn

map.has-key() belongs to the built-in sass:map module. It answers a yes/no question: does this key (or nested path) exist? This page covers true/false results, vs map.get, nested checks (Dart Sass 1.27+), @if guards, and five compiled examples.

What Is map.has-key()?

Theme maps often have optional tokens. Before you emit a CSS variable, you may want to know whether a key is present—even if its value is false or null. Official docs: with only $key, has-key returns whether the map contains that top-level key. With extra keys, it walks nested maps and checks the last key.

• One key → top-level existence check
• Several keys → nested path check (Dart Sass 1.27+)
• Always returns a boolean—never the stored value

📝 Syntax

Load the map module, then call the function:

@use "sass:map";

map.has-key($map, $key, $keys...)

// Legacy global name (still works)
map-has-key($map, $key)

Parameters

Return value

📦 Loading sass:map

// Recommended — namespaced
@use "sass:map";
$ok: map.has-key($theme, "colors", "primary");

// Optional — bring members into scope
@use "sass:map" as *;
$ok: has-key($theme, "colors", "primary");

// Optional — custom namespace
@use "sass:map" as m;
$ok: m.has-key($theme, "colors", "primary");

// Legacy global (flat keys)
$ok: map-has-key($font-weights, "regular");

🔍 Flat Check vs Nested Path

Official behavior matches map.get’s path rules, but returns a boolean:

• No extra keys — true if $key is in $map
• Extra keys — walk nested maps; test the last key; false if any step fails

@use "sass:map";

// Flat
map.has-key($font-weights, "regular"); // true

// Nested path: Helvetica → weights → regular
map.has-key($fonts, "Helvetica", "weights", "regular"); // true

📋 map.has-key vs map.get

This is the key beginner trap: a stored false or null is still a present key.

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS only contains the finished values you emit after the check.

Examples Gallery

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

@use "sass:map";

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

@debug map.has-key($font-weights, "regular"); // true
@debug map.has-key($font-weights, "bolder"); // false

.weights {
  --regular: #{map.has-key($font-weights, "regular")};
  --bolder: #{map.has-key($font-weights, "bolder")};
}

.weights {
  --regular: true;
  --bolder: false;
}

@use "sass:map";

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

@debug map.has-key($fonts, "Helvetica", "weights", "regular"); // true
@debug map.has-key($fonts, "Helvetica", "colors"); // false

.fonts {
  --regular: #{map.has-key($fonts, "Helvetica", "weights", "regular")};
  --colors: #{map.has-key($fonts, "Helvetica", "colors")};
}

.fonts {
  --regular: true;
  --colors: false;
}

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

$config: (
  "enabled": false,
  "label": null
);

.compare {
  --has-enabled: #{map.has-key($config, "enabled")};
  --get-enabled: #{meta.inspect(map.get($config, "enabled"))};
  --has-label: #{map.has-key($config, "label")};
  --get-label: #{meta.inspect(map.get($config, "label"))};
  --has-ghost: #{map.has-key($config, "ghost")};
  --get-ghost: #{meta.inspect(map.get($config, "ghost"))};
}

.compare {
  --has-enabled: true;
  --get-enabled: false;
  --has-label: true;
  --get-label: null;
  --has-ghost: false;
  --get-ghost: null;
}

@use "sass:map";

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

.theme {
  @if map.has-key($theme, "colors", "accent") {
    --accent: #{map.get($theme, "colors", "accent")};
  }
  @if not map.has-key($theme, "shadow") {
    --shadow: none;
  }
  --has-radius: #{map.has-key($theme, "radius")};
}

.theme {
  --accent: #e67e22;
  --shadow: none;
  --has-radius: true;
}

@use "sass:map";

$flat: (
  "token": 1rem
);

.broken {
  --deep: #{map.has-key($flat, "token", "size")};
}

.broken {
  --deep: false;
}

🚀 Real-World Use Cases

• Optional theme tokens — emit CSS variables only when a key exists.
• Feature flags in maps — distinguish “key present and false” from “key missing”.
• Mixin APIs — accept a config map and branch on which options were passed.
• Safe nested reads — check the path with has-key before get.
• Typography scales — verify a weight exists before applying it (docs sample).

⚠️ Common Pitfalls

• Using get as a boolean — a stored false looks “off” even though the key exists.
• Assuming nested keys everywhere — multi-key has-key needs Dart Sass 1.27+.
• Expecting the value back — has-key only returns true/false; use get to read.
• Broken middle keys — if a path step is not a map, the result is false.
• Forgetting quotes — string keys must match how the map was written.

💡 Best Practices