map.has-key($map, $key, $keys...) returns true if the map contains that key, otherwise false. With extra keys it checks a nested path the same way map.get walks nested maps. Load it with @use "sass:map" on Dart Sass 1.23+ (nested multi-key paths need a current Dart Sass release). Legacy global name: map-has-key.
map.has-key(("regular": 400, "medium": 500, "bold": 700), "regular") → true. Missing "bolder" → false. Nested: map.has-key($fonts, "Helvetica", "weights", "regular") → true.
A key can exist and still store false, 0, or null. has-key stays true; map.get returns that falsy value.
Official docs: if any key is missing or points at a non-map before the end, has-key returns false.
@use "sass:map";
map.has-key($map, $key); //=> boolean
map.has-key($map, $key, $keys...); // nested path (Dart Sass)
map.has-key($font-weights, "regular"); // true
map.has-key($font-weights, "bolder"); // false
map.has-key($fonts, "Helvetica", "weights", "regular"); // true
// Legacy global (prefer module form)
// map-has-key($map, $key);Pattern: map.has-key to guard → map.get to read → optional @if for conditional CSS.
Pick the helper based on whether you need existence or the stored value:
| Goal | Use |
|---|---|
| Does this key exist? | map.has-key($map, $key) |
| What is the value? | map.get($map, $key) |
| Nested path check | map.has-key($map, $k1, $k2, …) |
Key stores false / 0 / null | has-key → true; get → that value |
Default with or | Risky for falsy tokens — prefer has-key first |
| Conditional CSS | @if map.has-key(...) |
Earlier keys navigate nested maps; the last key is the one whose presence is tested.
Examples target Dart Sass with @use "sass:map". Open View Compiled CSS for verified output (matches official Sass docs samples).
Ask whether a top-level key is present.
@use "sass:map";
$font-weights: ("regular": 400, "medium": 500, "bold": 700);
.flat {
--regular: #{map.has-key($font-weights, "regular")};
--bolder: #{map.has-key($font-weights, "bolder")};
}regular exists → true.bolder is absent → false.Pass multiple keys to test a nested entry.
@use "sass:map";
$fonts: (
"Helvetica": (
"weights": (
"regular": 400,
"medium": 500,
"bold": 700
)
)
);
.nested {
--regular: #{map.has-key($fonts, "Helvetica", "weights", "regular")};
--colors: #{map.has-key($fonts, "Helvetica", "colors")};
}Helvetica → weights → regular.true.colors branch → false.Existence is separate from truthiness.
@use "sass:map";
@use "sass:meta";
$flags: (debug: false, verbose: null, count: 0);
.falsy {
--debug-has: #{map.has-key($flags, debug)};
--debug-get: #{meta.inspect(map.get($flags, debug))};
--verbose-has: #{map.has-key($flags, verbose)};
--count-has: #{map.has-key($flags, count)};
--or-debug: #{map.get($flags, debug) or true};
}debug exists even though its value is false.or ignores that stored false and takes the fallback.null and 0 keys still report has-key: true.@ifEmit CSS only when a nested token is present.
@use "sass:map";
$theme: (colors: (primary: navy, accent: teal));
.guard {
@if map.has-key($theme, colors, accent) {
--accent: #{map.get($theme, colors, accent)};
}
@if map.has-key($theme, colors, ghost) {
--ghost: yes;
} @else {
--ghost: no;
}
}accent exists → custom property is emitted.ghost is missing → @else branch runs.@if over deprecated plain if() for control flow.Share one map; enable features only when keys are configured.
@use "sass:map";
$button: (
pad: 8px,
radius: 4px,
shadow: true
);
.btn {
padding: map.get($button, pad);
border-radius: map.get($button, radius);
@if map.has-key($button, shadow) {
--shadow: #{map.get($button, shadow)};
}
@if map.has-key($button, outline) {
outline: map.get($button, outline);
}
}map.get.shadow exists → optional custom property appears.outline is absent → no outline rule is compiled.Most has-key bugs are confusing it with get, or trusting or for falsy tokens.
has-key answers presence. Use get only after you know the key is there—or when null is an acceptable miss.
map.get($m, debug) or true turns a stored false into true. Check has-key first.
If an intermediate key holds a color or number, deeper checks return false.
Global map-has-key still works but is deprecated toward Dart Sass 3.0. Use the module API.
Prefer the module form with a current Dart Sass release. Nested multi-key checks need Dart Sass.
| API | Status |
|---|---|
map.has-key() | Dart Sass 1.23+ via @use "sass:map" |
Nested $keys... | Dart Sass (multi-argument has-key) |
Global map-has-key() | Works; deprecated toward Sass 3.0 |
| Return type | true or false |
Compile with the Dart Sass CLI.
map-has-key.One line: when you need to know if a key exists, call map.has-key($map, $key) or map.has-key($map, $path...).
Practical checklist:
1. @use "sass:map"
2. Use has-key for existence; get for values
3. Nested tokens: map.has-key($map, group, token)
4. Guard optional CSS with @if map.has-key(...)
5. Avoid global map-has-key in new codeGet a comma-separated list of every key in a map.
8 people found this page helpful