Sass map.get() Function

What You’ll Learn

map.get() belongs to the built-in sass:map module. It reads a value from a map by key—or by a nested key path. This page covers missing keys (null), map-get, nested lookup (Dart Sass 1.27+), defaults with or, and five compiled examples.

What Is map.get()?

Maps store named values—font weights, colors, radii. map.get is how you pull one value out so you can put it in CSS. Official docs: with only $key, you get the value for that top-level key (or null if it is missing). With extra keys, Sass walks nested maps and returns the value at the last key.

• One key → top-level lookup
• Several keys → nested path (Dart Sass 1.27+)
• Missing key or broken path → null, not an error

📝 Syntax

Load the map module, then call the function:

@use "sass:map";

map.get($map, $key, $keys...)

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

Parameters

Return value

📦 Loading sass:map

// Recommended — namespaced
@use "sass:map";
$primary: map.get($theme, "colors", "primary");

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

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

// Legacy global (flat keys)
$medium: map-get($font-weights, "medium");

🔍 Flat Lookup vs Nested Path

Official behavior splits cleanly into two cases:

• No extra keys — return the value for $key, or null
• Extra keys — walk left to right through nested maps; return the value for the last key, or null if any step fails

@use "sass:map";

// Flat
map.get($font-weights, "medium"); // 500

// Nested path: Helvetica → weights → regular
map.get($fonts, "Helvetica", "weights", "regular"); // 400

📋 map.get vs map.has-key

Both accept the same key-path style. Choose based on whether you need the value or a yes/no answer.

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS only contains the finished values you read from the map.

Examples Gallery

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

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

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

@debug map.get($font-weights, "medium"); // 500
@debug map.get($font-weights, "extra-bold"); // null

.weights {
  --medium: #{map.get($font-weights, "medium")};
  --missing: #{meta.inspect(map.get($font-weights, "extra-bold"))};
}

.weights {
  --medium: 500;
  --missing: null;
}

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

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

@debug map.get($fonts, "Helvetica", "weights", "regular"); // 400
@debug map.get($fonts, "Helvetica", "colors"); // null

.fonts {
  --regular: #{map.get($fonts, "Helvetica", "weights", "regular")};
  --colors: #{meta.inspect(map.get($fonts, "Helvetica", "colors"))};
}

.fonts {
  --regular: 400;
  --colors: null;
}

@use "sass:map";

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

.theme {
  --primary: #{map.get($theme, "colors", "primary")};
  --radius: #{map.get($theme, "radius")};
  --has-primary: #{map.has-key($theme, "colors", "primary")};
}

.theme {
  --primary: #336699;
  --radius: 8px;
  --has-primary: true;
}

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

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

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

.truthy {
  --enabled: false;
  --label: null;
  --missing: null;
}

@use "sass:map";

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

$weight: map.get($font-weights, "extra-bold") or 400;

.fallback {
  --weight: #{$weight};
}

.fallback {
  --weight: 400;
}

🚀 Real-World Use Cases

• Design tokens — read colors, spacing, and radii from a theme map into CSS.
• Typography scales — pull a single weight from a nested font map (docs sample).
• Component APIs — accept a config map and get only the options you need.
• Safe defaults — map.get(...) or $fallback for optional overrides.
• Guarded mixins — pair with map.has-key before using a nested branch.

⚠️ Common Pitfalls

• Treating null as an error — missing keys are normal; add a default or check has-key.
• Using or with boolean flags — a stored false is falsy, so a fallback may fire incorrectly.
• Nested keys on old tooling — multi-key map.get needs Dart Sass 1.27+.
• Expecting mutation — get only reads; use map.set / merge helpers to change maps.
• Forgetting quotes — string keys like "medium" must match how the map was written.

💡 Best Practices