Sass map.keys()

Beginner
10 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass map.keys listing all keys in a map as a comma-separated list
Definition

Definition and Usage

map.keys($map) returns a comma-separated list of all keys in $map, in map order. Load it with @use "sass:map" on Dart Sass 1.23+. Legacy global name: map-keys.

Official sample.

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

Top-level only.

Keys inside nested maps are not flattened. Pass the nested map itself—for example map.keys(map.get($theme, colors))—to list those keys.

Returns a list, not a map.

Use list helpers like list.length and list.nth, or loop with @each.

Syntax

Syntax

SCSS
@use "sass:map";

map.keys($map); //=> comma-separated list

map.keys(("regular": 400, "medium": 500, "bold": 700));
// "regular", "medium", "bold"

@each $name in map.keys($font-weights) {
  // use $name + map.get($font-weights, $name)
}

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

Pattern: map.keys for names → map.get for values → or loop the map directly with @each $key, $value in $map.

Reference

keys vs values

Both return comma-separated lists in the same map order:

GoalUse
List key namesmap.keys($map)
List stored valuesmap.values($map)
Count entrieslist.length(map.keys($map))
Nested map’s keysmap.keys(map.get($map, $group))
Loop names + values@each $k in map.keys($m) + map.get, or @each $k, $v in $m
Empty mapmap.keys(()) → ()
Order is stable.

Keys come back in the same order as the map—handy when class-name generation must match token 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 — List Keys (Official Docs)

Pull every key from a font-weight map.

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

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

.basic {
  --keys: #{meta.inspect(map.keys($font-weights))};
  --first: #{list.nth(map.keys($font-weights), 1)};
  --sep: #{list.separator(map.keys($font-weights))};
}

How It Works

  1. Three keys come back as a comma list.
  2. Order matches the original map.
  3. Separator is comma — confirmed with list.separator.
  4. Matches the official Sass docs sample.

Example 2 — Utility Classes with @each

Build a class per key, then read each value with map.get.

SCSS
@use "sass:map";

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

@each $name in map.keys($font-weights) {
  .fw-#{$name} {
    font-weight: map.get($font-weights, $name);
  }
}

How It Works

  1. map.keys supplies the loop names.
  2. Interpolation builds selectors like .fw-medium.
  3. map.get fetches the matching weight.
  4. Alternative: @each $name, $weight in $font-weights skips the extra get.

Example 3 — Keys of a Nested Map

List top-level groups, then keys inside one group.

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

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

.nested {
  --top: #{meta.inspect(map.keys($theme))};
  --colors: #{meta.inspect(map.keys(map.get($theme, colors)))};
}

How It Works

  1. Top-level keys are colors and space only.
  2. Nested color keys need a second map.keys on that submap.
  3. No automatic flatten across nesting levels.
  4. Useful when documenting or validating token groups.

Example 4 — Count Map Entries

Combine map.keys with list.length.

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

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

.count {
  --entries: #{list.length(map.keys($font-weights))};
  --also: #{list.length($font-weights)};
}

How It Works

  1. list.length(map.keys(...)) counts keys.
  2. Maps also count as lists of pairs, so list.length($map) matches.
  3. Either form works; keys is clearer when you already need the names.
  4. Handy for debug output and validation.

Example 5 — Empty Map

An empty map yields an empty key list.

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

.empty {
  --keys: #{meta.inspect(map.keys(()))};
  --len: #{list.length(map.keys(()))};
}

How It Works

  1. Empty map → empty list ().
  2. Length is 0.
  3. Safe to loop — @each simply emits nothing.
  4. Guard with length if empty maps should warn or error.

Edge Cases & Pitfalls

Most map.keys bugs are expecting nested keys, or forgetting the result is a list.

nested

No deep key dump

map.keys($theme) will not include primary. Call keys on the nested map you care about.

type

Result is a list

Do not call map.get on the keys list. Use list helpers or @each.

loop

Keys alone are not values

After @each $k in map.keys($m), still call map.get($m, $k)—or destructure the map directly.

legacy

Prefer map.keys over map-keys

Global map-keys 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.keys()Dart Sass 1.23+ via @use "sass:map"
Global map-keys()Works; deprecated toward Sass 3.0
Return typeComma-separated list of keys
Empty mapEmpty list ()

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Returns every key as a comma-separated list in map order.
  • Top-level only — nest with map.get first for deeper keys.
  • Great with @each for utility class generation.
  • Prefer map.keys over deprecated global map-keys.

One line: when you need the names in a map, call map.keys($map).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:map"
2. Use map.keys for names; map.values for values
3. Nested keys: map.keys(map.get($map, $group))
4. Loop: @each $k in map.keys($m) { map.get($m, $k) }
5. Avoid global map-keys in new code

Frequently Asked Questions

map.keys($map) returns a comma-separated list of all keys in the map, in the same order as the map. It does not return nested keys from child maps—only the top level of the map you pass.
map.keys returns the names (keys). map.values returns the stored values in the same order. Use keys when you need names for @each or selectors; use values when you only need the numbers/colors.
Yes. map-keys($map) is the older global name, but Dart Sass deprecates global built-ins toward Sass 3.0. Prefer map.keys after @use "sass:map".
No. map.keys only lists keys of the map you pass. To list keys inside a nested map, first get that nested map: map.keys(map.get($theme, colors)).
map.keys(()) returns an empty list (). list.length of that list is 0.
Use @each $key in map.keys($map) { ... } and often map.get($map, $key) inside the loop to read each value. You can also @each $key, $value in $map directly.

Next: Sass map.merge()

Combine two maps—or merge into a nested path.

map.merge() →

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