Sass Map Functions — Key-Value Data Structures

In this tutorial, you will learn about Sass Map Functions. We cover key concepts, practical examples, and best practices to help you master this topic.

Sass map functions from the sass:map module store and manipulate key-value data for configuration, themes, breakpoints, and design tokens.

What You'll Learn

You will learn the essential map functions: map-get, map-merge, map-keys, map-values, map-has-key, and map-remove for structured data management.

Why It Matters

Maps organize related data. DodaTech uses maps for breakpoints, theme colors, z-index layers, and component configuration.

Real-World Use

Durga Antivirus Pro uses a nested map for all design tokens organized by category (colors, spacing, typography, shadows) with map functions for access.

flowchart LR
    A[List Functions] --> B[Map Functions]
    B --> C[Get/Set]
    B --> D[Examine]
    B --> E[Iterate]
    B --> F[Nested Maps]
    style B fill:#c69,stroke:#c69,color:#fff
    style C fill:#22c55e,stroke:#16a34a,color:#fff

Creating and Accessing Maps

@use "sass:map";

$breakpoints: (
  sm: 576px,
  md: 768px,
  lg: 992px,
  xl: 1200px,
);

// Access values
$md-value: map.get($breakpoints, md);     // 768px
$lg-value: map.get($breakpoints, lg);     // 992px
$missing: map.get($breakpoints, xxl);     // null

// Check key existence
$has-sm: map.has-key($breakpoints, sm);  // true
$has-xxl: map.has-key($breakpoints, xxl); // false

Expected output: Map values retrieved by key, with existence checks.

Modifying Maps

@use "sass:map";

$config: (
  padding: 1rem,
  color: #333,
  border: 1px solid #ddd,
);

// Add or update a key
$config: map.set($config, background, white);
// (padding: 1rem, color: #333, border: 1px solid #ddd, background: white)

// Merge two maps
$overrides: (color: #7c3aed, border: 2px solid #7c3aed);
$config: map.merge($config, $overrides);
// color and border are overridden, padding stays

// Remove keys
$config: map.remove($config, border);
// border key is removed

Expected output: Modified maps with added, updated, and removed keys.

Iterating Over Maps

$breakpoints: (sm: 576px, md: 768px, lg: 992px);

// Generate responsive utility classes
@each $name, $value in $breakpoints {
  @media (min-width: $value) {
    .text-#{$name}-center { text-align: center; }
    .text-#{$name}-right { text-align: right; }
  }
}

Expected output: Generated media query utility classes from map iteration.

Getting Map Metadata

@use "sass:map";

$theme: (
  primary: #7c3aed,
  secondary: #64748b,
  success: #10b981,
  danger: #ef4444,
);

// All keys
$keys: map.keys($theme);
// primary, secondary, success, danger

// All values
$values: map.values($theme);
// #7c3aed, #64748b, #10b981, #ef4444

// Count entries
$count: map.length($theme); // 4

// Deep merge check
$result: map.deep-merge(
  (colors: (primary: #7c3aed)),
  (colors: (secondary: #64748b))
);
// (colors: (primary: #7c3aed, secondary: #64748b))

Expected output: Map metadata and deep merge for nested structures.

Nested Maps

$theme: (
  colors: (
    brand: #7c3aed,
    accent: #f59e0b,
    neutral: (
      100: #f8fafc,
      500: #64748b,
      900: #0f172a,
    ),
  ),
  spacing: (
    sm: 0.5rem,
    md: 1rem,
    lg: 1.5rem,
  ),
);

// Access nested values
$brand-color: map.get($theme, colors, brand);           // #7c3aed
$neutral-500: map.get($theme, colors, neutral, 500);    // #64748b

Expected output: Nested map structure with deep key access.

Map for Component Config

$button-config: (
  default: (
    bg: #7c3aed,
    color: white,
    border: none,
    padding: 0.5rem 1rem,
  ),
  outline: (
    bg: transparent,
    color: #7c3aed,
    border: 2px solid #7c3aed,
    padding: 0.5rem 1rem,
  ),
  large: (
    padding: 0.75rem 1.5rem,
    font-size: 1.125rem,
  ),
);

@mixin button-style($variant: default) {
  $config: map.get($button-config, $variant);
  background: map.get($config, bg);
  color: map.get($config, color);
  border: map.get($config, border);
  padding: map.get($config, padding);

  @if map.has-key($config, font-size) {
    font-size: map.get($config, font-size);
  }
}

.btn-default { @include button-style(default); }
.btn-outline { @include button-style(outline); }
.btn-large { @include button-style(large); }

Expected output: Three button variants generated from a configuration map.

Safety Checks

@use "sass:map";

@function safe-get($map, $keys...) {
  $current: $map;
  @each $key in $keys {
    @if type-of($current) == map and map.has-key($current, $key) {
      $current: map.get($current, $key);
    } @else {
      @return null;
    }
  }
  @return $current;
}

$theme: (colors: (primary: #7c3aed));

.brand {
  color: safe-get($theme, colors, primary);  // #7c3aed
  // null instead of error for missing keys
}

Expected output: Safe access to nested map values without error.

Common Mistakes

1. Accessing Missing Keys

map.get($map, nonexistent) returns null, which compiles to empty property values. Use map.has-key to check first.

2. Forgetting map.merge Returns New Map

map.merge does not modify the original map. Assign the result to a variable.

3. Nested Map Confusion

Deeply nested maps become hard to read and access. Use deep-merge for combining and keep nesting to 2-3 levels.

4. Map Values Modifying Unexpectedly

Maps are immutable. Operations return new maps. The original remains unchanged.

5. Non-String Keys

Keys can be any type (strings, numbers, colors). String keys are most common and readable.

Practice Questions

1. How do you get a value from a map? map.get($map, $key) returns the value for the given key.

2. How do you combine two maps? map.merge($map1, $map2) merges, with map2 values overriding map1.

3. How do you check if a key exists? map.has-key($map, $key) returns true or false.

4. How do you iterate over a map? @each $key, $value in $map { ... } loops through all entries.

5. How do you get all keys from a map? map.keys($map) returns a list of all keys.

Challenge

Create a design token system using nested maps. Include categories for colors (with shades), typography (family, size, weight), spacing (xs through xl), and breakpoints. Write functions that retrieve token values by dot-notation path (e.g., token(colors.primary)).

FAQ

Mini Project

Build a component configuration system using maps. Define configuration maps for card, button, alert, and badge components. Each config includes colors, spacing, font sizes, and border settings. Write a @mixin that renders any component from its configuration map.

What's Next

Learn Sass Extend and Inheritance for sharing styles between selectors. Then explore Placeholder Selectors for silent extend-only classes.