Sass map.values()

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

Definition and Usage

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

Official sample.

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

Top-level only.

Nested maps are not flattened. A nested map value appears as one list item. Pass that nested map to map.values when you need its leaf values.

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.values($map); //=> comma-separated list

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

@each $weight in map.values($font-weights) {
  // use $weight
}

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

Pattern: map.values for data → map.keys for names → or loop both with @each $key, $value in $map.

Reference

values vs keys

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

GoalUse
List stored valuesmap.values($map)
List key namesmap.keys($map)
Count entrieslist.length(map.values($map))
Nested map’s valuesmap.values(map.get($map, $group))
Loop values only@each $v in map.values($m)
Loop names + values@each $k, $v in $m
Order matches keys.

Value position n lines up with key position n from map.keys.

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 Values (Official Docs)

Pull every value from a font-weight map.

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

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

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

How It Works

  1. Three values 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 — values vs keys

Same order, different content.

SCSS
@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))};
}

How It Works

  1. Keys are the token names.
  2. Values are the stored numbers.
  3. Positions align — first key pairs with first value.
  4. Pick based on whether you need names or data.

Example 3 — Reduce Values with @each

Sum every weight without caring about key names.

SCSS
@use "sass:map";

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

$sum: 0;
@each $weight in map.values($font-weights) {
  $sum: $sum + $weight;
}

.sum {
  --total: #{$sum};
}

How It Works

  1. map.values supplies 400, 500, 700.
  2. @each visits each number.
  3. Running total becomes 1600.
  4. Need names too? Prefer @each $name, $weight in $font-weights.

Example 4 — Values of a Nested Map

Top-level values can themselves be maps.

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

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

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

How It Works

  1. Top-level values are two nested maps.
  2. No flatten into navy, teal, 8px, 16px.
  3. Second call on the colors submap lists leaf colors.
  4. Same rule as map.keys for nesting.

Example 5 — Empty Map

An empty map yields an empty value list.

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

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

How It Works

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

Edge Cases & Pitfalls

Most map.values bugs are expecting a deep flatten, or forgetting the result is a list.

nested

No deep value dump

map.values($theme) will not list navy if it lives under colors. Call values on the nested map.

type

Result is a list

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

names

Values alone lose names

If selectors need key names, use map.keys or @each $k, $v in $map.

legacy

Prefer map.values over map-values

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

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Returns every value as a comma-separated list in map order.
  • Top-level only — nest with map.get first for deeper values.
  • Great with @each when you only need the data.
  • Prefer map.values over deprecated global map-values.

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

Practice

Compile Notes

Practical checklist:

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

Frequently Asked Questions

map.values($map) returns a comma-separated list of all values in the map, in the same order as the map’s keys. It does not flatten nested maps—nested map values appear as map items in the list.
map.keys returns the names (keys). map.values returns the stored values in the same order. Use keys when you need names; use values when you only need the numbers, colors, or other data.
Yes. map-values($map) is the older global name, but Dart Sass deprecates global built-ins toward Sass 3.0. Prefer map.values after @use "sass:map".
No automatic deep flatten. map.values only lists values of the map you pass. To list values inside a nested map, first get that nested map: map.values(map.get($theme, colors)).
map.values(()) returns an empty list (). list.length of that list is 0.
Use @each $value in map.values($map) { ... }. If you also need the key name, prefer @each $key, $value in $map or loop map.keys and call map.get.

Next: Sass meta.accepts-content()

Move into sass:meta — detect whether a mixin accepts @content.

meta.accepts-content() →

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.set Function Sass meta.accepts-content Function