sass-site/source/documentation/modules/map.liquid

---
title: sass:map
---

{% render 'documentation/snippets/built-in-module-status' %}

{% funFact false %}
  {% markdown %}
    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:
  {% endmarkdown %}

  {% codeExample 'map', false %}
    $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
  {% endcodeExample %}
{% endfunFact %}

{% function 'map.deep-merge($map1, $map2)', 'returns:map' %}
  {% compatibility 'dart: "1.27.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}

  {% markdown %}
    Identical to [`map.merge()`](#merge), except that nested map values are
    *also* recursively merged.
  {% endmarkdown %}

  {% codeExample 'map-deep-merge', false %}
    $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
    //   )
    // )
  {% endcodeExample %}
{% endfunction %}

{% function 'map.deep-remove($map, $key, $keys...)', 'returns:map' %}
  {% compatibility 'dart: "1.27.0"', 'libsass: false', 'ruby: false' %}{% endcompatibility %}

  {% markdown %}
    If `$keys` is empty, returns a copy of `$map` without a value associated
    with `$key`.
  {% endmarkdown %}

  {% codeExample 'map-deep-remove', false %}
    $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)
  {% endcodeExample %}

  {% markdown %}
    ---

    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`.
  {% endmarkdown %}

  {% codeExample 'map-deep-remove-2', false %}
    $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
    //     )
    //   )
    // )
  {% endcodeExample %}
{% endfunction %}

{% function 'map.get($map, $key, $keys...)', 'map-get($map, $key, $keys...)' %}
  {% markdown %}
    If `$keys` is empty, returns the value in `$map` associated with `$key`.

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

    [`null`]: /documentation/values/null
  {% endmarkdown %}

  {% render 'code-snippets/example-map-get' %}

  {% markdown %}
    ---

    {% compatibility 'dart: "1.27.0"', 'libsass: false', 'ruby: false' %}
      Only Dart Sass supports calling `map.get()` with more than two arguments.
    {% endcompatibility %}

    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.

    [`null`]: /documentation/values/null
  {% endmarkdown %}

  {% codeExample 'map-deep-remove-2', false %}
    $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
  {% endcodeExample %}
{% endfunction %}

{% function 'map.has-key($map, $key, $keys...)', 'map-has-key($map, $key, $keys...)', 'returns:boolean' %}
  {% markdown %}
    If `$keys` is empty, returns whether `$map` contains a value associated with
    `$key`.
  {% endmarkdown %}

  {% codeExample 'map-has-key', 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
    ===
    $font-weights: ("regular": 400, "medium": 500, "bold": 700)

    @debug map.has-key($font-weights, "regular") // true
    @debug map.has-key($font-weights, "bolder") // false
  {% endcodeExample %}

  {% markdown %}
    ---

    {% compatibility 'dart: "1.27.0"', 'libsass: false', 'ruby: false' %}
      Only Dart Sass supports calling `map.has-key()` with more than two
      arguments.
    {% endcompatibility %}

    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.
  {% endmarkdown %}

  {% codeExample 'map-has-key-2', 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
    ===
    $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
  {% endcodeExample %}
{% endfunction %}

{% function 'map.keys($map)', 'map-keys($map)', 'returns:list' %}
  {% markdown %}
    Returns a comma-separated list of all the keys in `$map`.
  {% endmarkdown %}

  {% codeExample 'map-keys', false %}
    $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"
  {% endcodeExample %}
{% endfunction %}

{% function 'map.merge($map1, $map2)', 'map-merge($map1, $map2)', 'map.merge($map1, $keys..., $map2)', 'map-merge($map1, $keys..., $map2)', 'returns:map' %}
  {% headsUp %}
    In practice, the actual arguments to `map.merge($map1, $keys..., $map2)` are
    passed as `map.merge($map1, $args...)`. They are described here as `$map1,
    $keys..., $map2` for explanation purposes only.
  {% endheadsUp %}

  {% markdown %}
    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.
  {% endmarkdown %}

  {% codeExample 'map-merge', false %}
    $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)
  {% endcodeExample %}

  {% markdown %}
    ---

    {% compatibility 'dart: "1.27.0"', 'libsass: false', 'ruby: false' %}
      Only Dart Sass supports calling `map.merge()` with more than two
      arguments.
    {% endcompatibility %}

    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`.
  {% endmarkdown %}

  {% codeExample 'map-merge-2', false %}
    $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
    //     )
    //   )
    // )
  {% endcodeExample %}
{% endfunction %}

{% function 'map.remove($map, $keys...)', 'map-remove($map, $keys...)', 'returns:map' %}
  {% markdown %}
    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.
  {% endmarkdown %}

  {% codeExample 'map-remove', false %}
    $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)
  {% endcodeExample %}
{% endfunction %}

{% function 'map.set($map, $key, $value)', 'map.set($map, $keys..., $key, $value)', 'returns:map' %}
  {% headsUp %}
    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.
  {% endheadsUp %}

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

  {% codeExample 'map-set', false %}
    $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)
  {% endcodeExample %}

  {% markdown %}
    ---

    {% compatibility 'dart: "1.27.0"', 'libsass: false', 'ruby: false' %}
      Only Dart Sass supports calling `map.set()` with more than three
      arguments.
    {% endcompatibility %}

    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`.
  {% endmarkdown %}

  {% codeExample 'map-set-2', false %}
    $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
    //     )
    //   )
    // )
  {% endcodeExample %}
{% endfunction %}

{% function 'map.values($map)', 'map-values($map)', 'returns:list' %}
  {% markdown %}
    Returns a comma-separated list of all the values in `$map`.
  {% endmarkdown %}

  {% codeExample 'map-values', false %}
    $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
  {% endcodeExample %}
{% endfunction %}