sass-site/source/documentation/modules/map.html.md.erb

---
title: sass:map
---

<%= partial '../snippets/built-in-module-status' %>

<% fun_fact do %>
  Sass libraries and design systems tend to share and override configurations
  that are represented as nested maps (maps that contain maps that contain
  maps).

  To help you work with nested maps, some map functions support deep
  operations. For example, if you pass multiple keys to `map.get()`, it will
  follow those keys to find the desired nested map:

  <% example(autogen_css: false) do %>
    $config: (a: (b: (c: d)));
    @debug map.get($config, a, b, c)); // d
    ===
    $config: (a: (b: (c: d)))
    @debug map.get($config, a, b, c)) // d
  <% end %>
<% end %>


<% function 'map.deep-merge($map1, $map2)', returns: 'map' do %>
  Identical to [`map.merge()`](#merge), except that nested map values are *also*
  recursively merged.

  <% example(autogen_css: false) do %>
    $helvetica-light: (
      "weights": (
        "lightest": 100,
        "light": 300
      )
    );
    $helvetica-heavy: (
      "weights": (
        "medium": 500,
        "bold": 700
      )
    );

    @debug map.deep-merge($helvetica-light, $helvetica-heavy);
    // (
    //   "weights": (
    //     "lightest": 100,
    //     "light": 300,
    //     "medium": 500,
    //     "bold": 700
    //   )
    // )
    @debug map.merge($helvetica-light, $helvetica-heavy);
    // (
    //   "weights": (
    //     "medium: 500,
    //     "bold": 700
    //   )
    // )
    ===
    $helvetica-light: ("weights": ("lightest": 100, "light": 300))
    $helvetica-heavy: ("weights": ("medium": 500, "bold": 700))

    @debug map.deep-merge($helvetica-light, $helvetica-heavy)
    // (
    //   "weights": (
    //     "lightest": 100,
    //     "light": 300,
    //     "medium": 500,
    //     "bold": 700
    //   )
    // )
    @debug map.merge($helvetica-light, $helvetica-heavy);
    // (
    //   "weights": (
    //     "medium: 500,
    //     "bold": 700
    //   )
    // )
  <% end %>
<% end %>


<% function 'map.deep-remove($map, $key, $keys...)',
            returns: 'map' do %>
  If `$keys` is empty, returns a copy of `$map` without a value associated with
  `$key`.

  <% example(autogen_css: false) do %>
    $font-weights: ("regular": 400, "medium": 500, "bold": 700);

    @debug map.deep-remove($font-weights, "regular");
    // ("medium": 500, "bold": 700)
    ===
    $font-weights: ("regular": 400, "medium": 500, "bold": 700)

    @debug map.deep-remove($font-weights, "regular")
    // ("medium": 500, "bold": 700)
  <% end %>

  ---

  If `$keys` is not empty, follows the set of keys including `$key` and
  excluding the last key in `$keys`, from left to right, to find the nested map
  targeted for updating.

  Returns a copy of `$map` where the targeted map does not have a value
  associated with the last key in `$keys`.

  <% example(autogen_css: false) do %>
    $fonts: (
      "Helvetica": (
        "weights": (
          "regular": 400,
          "medium": 500,
          "bold": 700
        )
      )
    );

    @debug map.deep-remove($fonts, "Helvetica", "weights", "regular");
    // (
    //   "Helvetica": (
    //     "weights: (
    //       "medium": 500,
    //       "bold": 700
    //     )
    //   )
    // )
    ===
    $fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700)))

    @debug map.deep-remove($fonts, "Helvetica", "weights", "regular")
    // (
    //   "Helvetica": (
    //     "weights: (
    //       "medium": 500,
    //       "bold": 700
    //     )
    //   )
    // )
  <% end %>
<% end %>


<% function 'map.get($map, $key, $keys...)',
            'map-get($map, $key, $keys...)' do %>
  If `$keys` is empty, returns the value in `$map` associated with `$key`.

  If `$map` doesn't have a value associated with `$key`, returns [`null`][].

  <%= partial 'code-snippets/example-map-get' %>

  ---

  If `$keys` is not empty, follows the set of keys including `$key` and
  excluding the last key in `$keys`, from left to right, to find the nested map
  targeted for searching.

  Returns the value in the targeted map associated with the last key in `$keys`.

  Returns [`null`][] if the map does not have a value associated with the key,
  or if any key in `$keys` is missing from a map or references a value that is
  not a map.

  <% example(autogen_css: false) do %>
    $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: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700)))

    @debug map.get($fonts, "Helvetica", "weights", "regular") // 400
    @debug map.get($fonts, "Helvetica", "colors") // null
  <% end %>

  [`null`]: ../values/null
<% end %>


<% function 'map.has-key($map, $key, $keys...)',
            'map-has-key($map, $key, $keys...)',
            returns: 'boolean' do %>
  If `$keys` is empty, returns whether `$map` contains a value associated with
  `$key`.

  <% example(autogen_css: false) do %>
    $font-weights: ("regular": 400, "medium": 500, "bold": 700);

    @debug map.has-key($font-weights, "regular"); // true
    @debug map.has-key($font-weights, "bolder"); // false
    ===
    $font-weights: ("regular": 400, "medium": 500, "bold": 700)

    @debug map.has-key($font-weights, "regular") // true
    @debug map.has-key($font-weights, "bolder") // false
  <% end %>

  ---

  If `$keys` is not empty, follows the set of keys including `$key` and
  excluding the last key in `$keys`, from left to right, to find the nested map
  targeted for searching.

  Returns true if the targeted map contains a value associated with the last key
  in `$keys`.

  Returns false if it does not, or if any key in `$keys` is missing from a map
  or references a value that is not a map.

  <% example(autogen_css: false) do %>
    $fonts: (
      "Helvetica": (
        "weights": (
          "regular": 400,
          "medium": 500,
          "bold": 700
        )
      )
    );

    @debug map.has-key($fonts, "Helvetica", "weights", "regular"); // true
    @debug map.has-key($fonts, "Helvetica", "colors"); // false
    ===
    $fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700)))

    @debug map.has-key($fonts, "Helvetica", "weights", "regular") // true
    @debug map.has-key($fonts, "Helvetica", "colors") // false
  <% end %>
<% end %>


<% function 'map.keys($map)', 'map-keys($map)', returns: 'list' do %>
  Returns a comma-separated list of all the keys in `$map`.

  <% example(autogen_css: false) do %>
    $font-weights: ("regular": 400, "medium": 500, "bold": 700);

    @debug map.keys($font-weights); // "regular", "medium", "bold"
    ===
    $font-weights: ("regular": 400, "medium": 500, "bold": 700)

    @debug map.keys($font-weights)  // "regular", "medium", "bold"
  <% end %>
<% end %>


<% function 'map.merge($map1, $map2)',
            'map-merge($map1, $map2)',
            'map.merge($map1, $keys..., $map2)',
            'map-merge($map1, $keys..., $map2)',
            returns: 'map' do %>
  <% heads_up do %>
    In practice, the actual arguments to `map.merge($map1, $keys..., $map2)`
    are passed as `map.set($map1, $args...)`. They are described here as `$map1,
    $keys..., $map2` for explanation purposes only.
  <% end %>

  If no `$keys` are passed, returns a new map with all the keys and values from
  both `$map1` and `$map2`.

  If both `$map1` and `$map2` have the same key, `$map2`'s value takes
  precedence.

  All keys in the returned map that also appear in `$map1` have the same order
  as in `$map1`. New keys from `$map2` appear at the end of the map.

  <% example(autogen_css: false) do %>
    $light-weights: ("lightest": 100, "light": 300);
    $heavy-weights: ("medium": 500, "bold": 700);

    @debug map.merge($light-weights, $heavy-weights);
    // ("lightest": 100, "light": 300, "medium": 500, "bold": 700)
    ===
    $light-weights: ("lightest": 100, "light": 300)
    $heavy-weights: ("medium": 500, "bold": 700)

    @debug map.merge($light-weights, $heavy-weights)
    // ("lightest": 100, "light": 300, "medium": 500, "bold": 700)
  <% end %>

  ---

  If `$keys` is not empty, follows the `$keys` to find the nested map targeted
  for merging. If any key in `$keys` is missing from a map or references a value
  that is not a map, sets the value at that key to an empty map.

  Returns a copy of `$map1` where the targeted map is replaced by a new map that
  contains all the keys and values from both the targeted map and `$map2`.

  <% example(autogen_css: false) do %>
    $fonts: (
      "Helvetica": (
        "weights": (
          "lightest": 100,
          "light": 300
        )
      )
    );
    $heavy-weights: ("medium": 500, "bold": 700);

    @debug map.merge($fonts, "Helvetica", "weights", $heavy-weights);
    // (
    //   "Helvetica": (
    //     "weights": (
    //       "lightest": 100,
    //       "light": 300,
    //       "medium": 500,
    //       "bold": 700
    //     )
    //   )
    // )
    ===
    $fonts: ("Helvetica": ("weights": ("lightest": 100, "light": 300)))
    $heavy-weights: ("medium": 500, "bold": 700)

    @debug map.merge($fonts, "Helvetica", "weights", $heavy-weights)
    // (
    //   "Helvetica": (
    //     "weights": (
    //       "lightest": 100,
    //       "light": 300,
    //       "medium": 500,
    //       "bold": 700
    //     )
    //   )
    // )
  <% end %>
<% end %>


<% function 'map.remove($map, $keys...)',
            'map-remove($map, $keys...)',
            returns: 'map' do %>
  Returns a copy of `$map` without any values associated with `$keys`.

  If a key in `$keys` doesn't have an associated value in `$map`, it's ignored.

  <% example(autogen_css: false) do %>
    $font-weights: ("regular": 400, "medium": 500, "bold": 700);

    @debug map.remove($font-weights, "regular"); // ("medium": 500, "bold": 700)
    @debug map.remove($font-weights, "regular", "bold"); // ("medium": 500)
    @debug map.remove($font-weights, "bolder");
    // ("regular": 400, "medium": 500, "bold": 700)
    ===
    $font-weights: ("regular": 400, "medium": 500, "bold": 700)

    @debug map.remove($font-weights, "regular")  // ("medium": 500, "bold": 700)
    @debug map.remove($font-weights, "regular", "bold")  // ("medium": 500)
    @debug map.remove($font-weights, "bolder")
    // ("regular": 400, "medium": 500, "bold": 700)
  <% end %>
<% end %>


<% function 'map.set($map, $key, $value)',
            'map.set($map, $keys..., $key, $value)',
            returns: 'map' do %>
  <% heads_up do %>
    In practice, the actual arguments to `map.set($map, $keys..., $key, $value)`
    are passed as `map.set($map, $args...). They are described here as `$map,
    $keys..., $key, $value` for explanation purposes only.
  <% end %>

  If `$keys` are not passed, returns a copy of `$map` with the value at `$key`
  set to `$value`.

  <% example(autogen_css: false) do %>
    $font-weights: ("regular": 400, "medium": 500, "bold": 700);

    @debug map.set($font-weights, "regular", 300);
    // ("regular": 300, "medium": 500, "bold": 700)
    ===
    $font-weights: ("regular": 400, "medium": 500, "bold": 700)

    @debug map.set($font-weights, "regular", 300)
    // ("regular": 300, "medium": 500, "bold": 700)
  <% end %>

  ---

  If `$keys` are passed, follows the `$keys` to find the nested map targeted for
  updating. If any key in `$keys` is missing from a map or references a value
  that is not a map, sets the value at that key to an empty map.

  Returns a copy of `$map` with the targeted map's value at `$key` set to
  `$value`.

  <% example(autogen_css: false) do %>
    $fonts: (
      "Helvetica": (
        "weights": (
          "regular": 400,
          "medium": 500,
          "bold": 700
        )
      )
    );

    @debug map.set($fonts, "Helvetica", "weights", "regular", 300);
    // (
    //   "Helvetica": (
    //     "weights": (
    //       "regular": 300,
    //       "medium": 500,
    //       "bold": 700
    //     )
    //   )
    // )
    ===
    $fonts: ("Helvetica": ("weights": ("regular": 400, "medium": 500, "bold": 700)))

    @debug map.set($fonts, "Helvetica", "weights", "regular", 300)
    // (
    //   "Helvetica": (
    //     "weights": (
    //       "regular": 300,
    //       "medium": 500,
    //       "bold": 700
    //     )
    //   )
    // )
  <% end %>
<% end %>


<% function 'map.values($map)', 'map-values($map)', returns: 'list' do %>
  Returns a comma-separated list of all the values in `$map`.

  <% example(autogen_css: false) do %>
    $font-weights: ("regular": 400, "medium": 500, "bold": 700);

    @debug map.values($font-weights); // 400, 500, 700
    ===
    $font-weights: ("regular": 400, "medium": 500, "bold": 700)

    @debug map.values($font-weights)  // 400, 500, 700
  <% end %>
<% end %>