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