sass-site/source/documentation/values/maps.html.md.erb

---
title: Maps
table_of_contents: true
---

Maps in Sass hold pairs of keys and values, and make it easy to look up a value
by its corresponding key. They're written
`(<expression>: <expression>, <expression>: <expression>)`. The [expression][]
before the `:` is the key, and the expression after is the value associated with
that key. The keys must be unique, but the values may be duplicated. Unlike
[lists][], maps *must* be written with parentheses around them. A map with no
pairs is written `()`.

[expression]: ../syntax/structure#expressions
[lists]: lists

<% fun_fact do %>
  Astute readers may note that an empty map, `()`, is written the same as an
  empty list. That's because it counts as both a map and a list. In fact, *all*
  maps count as lists! Every map counts as a list that contains a two-element
  list for each key/value pair. For example, `(1: 2, 3: 4)` counts as `(1 2, 3
  4)`.
<% end %>

Maps allow any Sass values to be used as their keys. The [`==` operator][] is
used to determine whether two keys are the same.

[`==` operator]: ../operators/equality

<% heads_up do %>
  Most of the time, it's a good idea to use [quoted strings][] rather than
  [unquoted strings][] for map keys. This is because some values, such as color
  names, may *look* like unquoted strings but actually be other types. To avoid
  confusing problems down the line, just use quotes!

  [quoted strings]: strings#quoted
  [unquoted strings]: strings#unquoted
<% end %>

## Using Maps

Since maps aren't valid CSS values, they don't do much of anything on their own.
That's why Sass provides a bunch of [functions][] to create maps and access the
values they contain. With

[functions]: ../functions/map

### Look Up a Value

Maps are all about associating keys and values, so naturally there's a way to
get the value associated with a key: the [`map-get($map, $key)` function][]!
This function returns the value in the map associated with the given key. It
returns [`null`][] if the map doesn't contain the key.

the [`map-get($map, $key)` function]: ../functions/map#map-get
[`null`]: null

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

### Do Something for Every Pair

This doesn't actually use a function, but it's still one of the most common ways
to use maps. The [`@each` rule][] evaluates a block of styles for each key/value
pair in a map. The key and the value are assigned to variables so they can
easily be accessed in the block.

The [`@each` rule]: ../at-rules/control/each

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

### Add to a Map

It's also useful to add new pairs to a map, or to replace the value for an
existing key. The [`map-merge($map1, $map2)` function][] does this: it returns a
new map that contains all the key/value pairs in *both* arguments.

[`map-merge($map1, $map2)` function]: ../functions/map#map-merge

<% 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 %>

`map-merge()` is often used with an inline map to add a single key/value pair.

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

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

  @debug map-merge($font-weights, ("extra-bold": 900))
  // ("regular": 400, "medium": 500, "bold": 700, "extra-bold": 900)
<% end %>

If both maps have the same keys, the second map's values are used in the map
that gets returned.

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

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

  @debug map-merge($font-weights, ("medium": 600))
  // ("regular": 400, "medium": 600, "bold": 700)
<% end %>

Note that because Sass maps are [immutable][], `map-merge()` doesn't modify the
original list.

[immutable]: #immutability