Sass/SCSS Map Collection Tutorial

In this Sass/SCSS tutorial we learn how to store multiple values in key:value format in a single data container called a map collection.

We cover how to define a map, how to access its values by key or in a loop and how to add values to an existing map.

Here's a table of contents of what you'll learn in this lesson:
(click on a link to skip to its section)

Let's jump right in.

What is a map collection

A map collection is similar to a list in that it stores multiple values in a single data container.

The difference between a map and a list is that we can specify a string as the indexer in a map in key:value format.

How to define a map

As mentioned before, we store values in a map in key:value format.

Unlike a list, a map must be defined inside parentheses and separated with commas. The keys in a map must be unique, but the values may be duplicate.

Syntax: SCSS
$map_name: ("key":value, "key":value);

When using a string as a key, remember to wrap it in quotes. In fact, it’s good practice to always use strings as keys.

Example: SCSS
$font-weight: ("light": 300, "regular": 400, "bold": 700);

In the example above we define a map with three items. Each item has a correspong string key.

How to access values in a map by key

Sass provides us with the map-get() function to retrieve values.

The map-get() function has two arguments. The first argument is the list we want to get the value from, and the second argument is the value’s corresponding key.

Syntax: SCSS
map-get(map_name, key);
Example: SCSS
$font-weight: ("light": 300, "regular": 400, "bold": 700);

body {
  font-weight: map-get($font-weight, "regular");

In the example above we get the value that’s assigned to the “regular” key, which is 400

Output: Compiled CSS
body {
  font-weight: 400;

How to access map items in a loop

We can access all the items in a map by using a loop, which will iterate through all the elements and execute a block of code for each.

We cover loops in depth in the Iteration Control lesson . Although any loop can be used, map collections really prefer the @each loop .

How to add values to a map

To add values to a map we have to create another new map, then merge it with the map we want to add the values to.

Sass provides us with the map-merge() function to combine maps.

This function takes two arguments that are simply the two maps we want to merge.

map-merge(map1, map2);
Example: SCSS
$light-weight: ("ultralight": 100, "light": 300, "regular": 400);
$heavy-weight: ("medium": 500, "semibold": 600, "bold": 700);

$font-weight: map-merge($light-weight, $heavy-weight);

body {
  font-weight: map-get($font-weight, "semibold");

Because the two maps were merged, we can get the “semibold” value from the new map.

Output: Compiled CSS
body {
  font-weight: 600;

Summary: Points to remember

  • A map is a data container that stores multiple values in a table-like structure in key:value format.
    • The key will act as the indexer in a map.
    • Sass maps are immutable, which means their values cannot be changed dynamically.
  • A map must be defined in parentheses with the elements separated by commas.
  • We use the built-in map-get() function to access a value via its key.
  • To add a value to a map we must first create another new map, them merge the two with the built-in map-merge() function.