Sass map.keys() Function

What You’ll Learn

map.keys() belongs to the built-in sass:map module. It returns every key in a map as a comma-separated list. This page covers order, @each loops, nested maps, vs map.values, the legacy map-keys name, and five compiled examples.

What Is map.keys()?

Maps store named pairs like "medium": 500. Sometimes you need the names—to loop, build class names, or count entries. Official docs: map.keys returns a comma-separated list of all keys in $map.

• Order matches the map’s key order
• Only top-level keys of the map you pass (not deep nested keys automatically)
• Result is a list—use list.length, list.nth, or @each

📝 Syntax

Load the map module, then call the function:

@use "sass:map";

map.keys($map)

// Legacy global name (still works)
map-keys($map)

Parameters

Return value

📦 Loading sass:map

// Recommended — namespaced
@use "sass:map";
$names: map.keys($theme);

// Optional — bring members into scope
@use "sass:map" as *;
$names: keys($theme);

// Optional — custom namespace
@use "sass:map" as m;
$names: m.keys($theme);

// Legacy global
$names: map-keys($theme);

📋 map.keys vs map.values

Both return comma-separated lists in the same order. Pick the side of each pair you need.

🔍 Top-Level Only (Nested Maps)

map.keys($theme) does not flatten nested keys. If $theme has a "colors" map inside, you only see "colors" at the top level. To list color token names, pass the nested map:

@use "sass:map";

map.keys($theme); // "colors", "radius"
map.keys(map.get($theme, "colors")); // "primary", "accent"

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS only contains the values you emit after looping or reading keys.

Examples Gallery

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

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

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

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

.weights {
  --all: #{meta.inspect(map.keys($font-weights))};
}

.weights {
  --all: "regular", "medium", "bold";
}

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

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

.keys {
  --all: #{meta.inspect(map.keys($font-weights))};
  --len: #{list.length(map.keys($font-weights))};
  --first: #{list.nth(map.keys($font-weights), 1)};
}

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

.keys {
  --all: "regular", "medium", "bold";
  --len: 3;
  --first: regular;
}

.empty {
  --keys: ();
  --len: 0;
}

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

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

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

.theme {
  --top: "colors", "radius";
  --color-keys: "primary", "accent";
}

@use "sass:map";

$spacing: (
  "sm": 0.5rem,
  "md": 1rem,
  "lg": 1.5rem
);

@each $name in map.keys($spacing) {
  .space-#{$name} {
    padding: map.get($spacing, $name);
  }
}

.space-sm {
  padding: 0.5rem;
}

.space-md {
  padding: 1rem;
}

.space-lg {
  padding: 1.5rem;
}

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

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

.compare {
  --keys: #{meta.inspect(map.keys($font-weights))};
  --values: #{meta.inspect(map.values($font-weights))};
}

.compare {
  --keys: "regular", "medium", "bold";
  --values: 400, 500, 700;
}

🚀 Real-World Use Cases

• Utility generators — build .space-sm-style classes from a token map.
• Theme introspection — list which top-level sections a config map defines.
• Validation — compare map.keys against an allowed-keys list.
• Docs / debug — print key names with meta.inspect while building systems.
• Nested tokens — map.keys(map.get(...)) to list color or type scale names.

⚠️ Common Pitfalls

• Expecting nested keys — keys is top-level only; dig with map.get first.
• Confusing keys with values — names vs stored data; use the matching helper.
• Forgetting it is a list — use list module helpers, not map helpers, on the result.
• Assuming quoted CSS output — interpolating a bare key may drop quotes; use meta.inspect when debugging.
• Empty maps — you get (), not an error.

💡 Best Practices