Sass map.get()

Beginner
10 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass map.get reading map values by key or nested path
Definition

Definition and Usage

map.get($map, $key, $keys...) returns the value associated with a key. With one key it reads the top level. With more keys it walks nested maps and returns the value at the last key. 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-get.

Official samples.

map.get(("regular": 400, "medium": 500, "bold": 700), "medium") → 500. Missing key → null. Nested: map.get($fonts, "Helvetica", "weights", "regular") → 400.

Read-only.

map.get never changes the map. Use map.set, map.merge, or map.deep-merge to produce updates.

null is not an error.

A missing key (or a broken nested path) returns null. Guard with map.has-key or supply a default with or.

Syntax

Syntax

SCSS
@use "sass:map";

map.get($map, $key);
map.get($map, $key, $keys...); // nested path (Dart Sass)

map.get($font-weights, "medium");              // 500
map.get($font-weights, "extra-bold");          // null
map.get($fonts, "Helvetica", "weights", "regular"); // 400

// Legacy global (prefer module form)
// map-get($map, $key);

Pattern: store tokens in a map → map.get in properties → confirm existence with map.has-key when null would be ambiguous.

Reference

Key vs Path

Use one key for flat maps; pass a path for nested design tokens:

CallResult
map.get($map, $key)Top-level value, or null
map.get($map, $k1, $k2, …)Walk nested maps; return last key’s value
Missing key / broken pathnull (no error)
Mid-path keyCan return a nested map if you stop early
Default valuemap.get($map, $key) or $fallback
Existence checkmap.has-key($map, $key, …)
Nested lookup rules.

Official docs: if any key is missing or points at a non-map before the end, the result is null.

Code

SCSS Examples

Examples target Dart Sass with @use "sass:map". Open View Compiled CSS for verified output (matches official Sass docs samples).

Example 1 — Read a Top-Level Key (Official Docs)

Look up a font weight by name.

SCSS
@use "sass:map";

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

.flat {
  font-weight: map.get($font-weights, "medium");
  --bold: #{map.get($font-weights, "bold")};
}

How It Works

  1. One key reads a top-level entry.
  2. "medium" resolves to 500.
  3. Emit directly into CSS properties or custom properties.
  4. Matches the official Sass docs sample.

Example 2 — Missing Key Returns null

Absent keys do not throw; they return null.

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

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

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

How It Works

  1. extra-bold is not in the map.
  2. map.get returns null.
  3. map.has-key returns false for the same key.
  4. Matches the official missing-key sample.

Example 3 — Nested Key Path (Official Docs)

Pass multiple keys to walk into nested maps.

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

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

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

How It Works

  1. Three keys reach the nested regular weight.
  2. Stopping at weights returns the nested map itself.
  3. Missing colors yields null.
  4. Matches the official nested-path sample.

Example 4 — Default with or

Provide a fallback when a token might be absent.

SCSS
@use "sass:map";

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

.defaults {
  --light: #{map.get($font-weights, "light") or 300};
  --medium: #{map.get($font-weights, "medium") or 400};
}

How It Works

  1. Missing light is null, so or 300 wins.
  2. Existing medium keeps 500.
  3. Handy for optional theme overrides.
  4. Watch falsy values — 0 or false also trigger or; use has-key when that matters.

Example 5 — Theme Tokens in CSS

Pull nested design tokens straight into declarations.

SCSS
@use "sass:map";

$theme: (
  colors: (primary: navy, accent: teal),
  button: (pad: 8px, radius: 4px)
);

.btn {
  color: map.get($theme, colors, primary);
  padding: map.get($theme, button, pad);
  border-radius: map.get($theme, button, radius);
  --accent: #{map.get($theme, colors, accent)};
}

How It Works

  1. Nested paths keep tokens organized by group.
  2. Values compile into normal CSS declarations.
  3. Same helper works for colors, spacing, and component maps.
  4. Pair with deep-merge when projects override a shared base theme.

Edge Cases & Pitfalls

Most map.get bugs are treating null as an error, or using or when a real value is falsy.

null

Missing ≠ crash

A bad path returns null. Check with map.has-key before assuming a value exists.

or

Falsy values trip defaults

0, false, or null all make or take the fallback. Prefer has-key when those are valid tokens.

path

Non-map mid-path

If an intermediate key holds a color or number, deeper keys resolve to null.

legacy

Prefer map.get over map-get

Global map-get 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. Nested multi-key paths need Dart Sass.

APIStatus
map.get()Dart Sass 1.23+ via @use "sass:map"
Nested $keys...Dart Sass (multi-argument get)
Global map-get()Works; deprecated toward Sass 3.0
Missing keyReturns null

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Reads a value by key or nested path without changing the map.
  • Missing keys return null — not an error.
  • Nested paths unlock design-token maps in Dart Sass.
  • Prefer map.get over deprecated global map-get.

One line: when you need a map value, call map.get($map, $key) or map.get($map, $path...).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:map"
2. Use map.get for reads; map.set / merge for writes
3. Nested tokens: map.get($map, group, token)
4. Guard missing keys with has-key or `or`
5. Avoid global map-get in new code

Frequently Asked Questions

map.get($map, $key, $keys...) returns the value for a key. With one key it reads the top level. With more keys (Dart Sass) it walks nested maps and returns the value at the last key.
It returns null. That is not an error. Use map.has-key() when you need a true/false check, or combine with or for a default: map.get($map, $key) or $default.
Yes. map-get($map, $key) is the older global name, but Dart Sass deprecates global built-ins toward Sass 3.0. Prefer map.get after @use "sass:map". Nested key paths need the module API.
map.get returns the stored value (or null). map.has-key returns true or false for whether the key exists—useful when the real value might be null, 0, or false.
Two-argument get works widely via map.get / map-get. Passing multiple keys for nested lookup is Dart Sass only. Prefer current Dart Sass for design-system maps.
No. It only reads. Use map.set, map.merge, or map.deep-merge when you need a new map with updates.

Next: Sass map.has-key()

Check whether a key—or nested path—exists before reading it.

map.has-key() →

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