Sass/SCSS List Collection Tutorial

What is a list collection

A list collection is a data container, like a variable. Unlike a variable, it stores multiple values in a table-like structure.

As an example, consider a list of predefined fixed sizes. It would be cumbersome to store items in such a list as separate variables, as well as to access them one by one.

A list allows us to store this collection of sizes in a single container.

How to define a list

A list is defined as a variable that contains multiple values.

Sass allows us to define the values of the list in various ways.

• Multiple values, separated with a comma.
• Multiple values, separated with spaces.
• Multiple values inside parentheses, separated with commas.
• Multiple values inside parentheses, separated with spaces.
• Multiple values inside square brackets, separated with spaces.

$list_name: values, separated, with, commas;

// or
$list_name: values separated with spaces;

// or
$list_name: (values, in, parens, separated, with, commas);

// or
$list_name: (values in parens separated with spaces);

// or
$list_name: [values in brackets separated with spaces];

$list-1: "Segoe UI",sans-serif;
$list-2: 10px 12px 10px 20px;
$list-3: ("Segoe UI",sans-serif);
$list-4: (10px 12px 10px 20px);
$list-5: [grid-line1 grid-line2];

Whichever style you use to define values is up to you, but stay consistent.

In this course we’ll define our lists as comma separated values between parentheses. We feel that it’s easier and faster to read. The commas make the separation easy to see at a glance and the parentheses show us it’s a list.

The list is like a table with a single row, but multiple columns. If we consider one of the examples above, it would look like this.

How to access list items with the indexer

To access a list element (a single value in the list), we use the indexer.

When we create a list, each value is assigned to a corresponding number, its index. If we think about a list as a table, we would add another row with numbers, starting at 1.

note List collections in most general purpose programming languages like C# or Python start their index at 0. List collections in Sass however, always start at 1.

These numbers form the index. When we want to access a specific element, we provide the compiler with that element’s corresponding index number in the list.nth() function.

The nth() function takes two arguments. The first argument is the list itself, and the second argument is the index number.

nth( (value1, value2, value3), index);

// or
$list_name: (value1, value2, value3, ...);
nth($list_name, index);

$font-sizes: (14px, 16px, 18px, 20px);

body {
  font-size: nth($font-sizes, 2);
}

In the examples above we tell the compiler to give us the second value in the list, 16px .

body {
  font-size: 16px;
}

We can also access values from the end of the list easily with negative values, like -1 .

$font-sizes: (14px, 16px, 18px, 20px);

body {
  font-size: nth($font-sizes, -2);
}

Because a list cannot have an element at a negative index, Sass knows to look from the end of the list when we provide a negative number.

In the examples above we access the second list item from the end of the list.

body {
  font-size: 18px;
}

How to access list items in a loop

We can access all the items in a list 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, list collections really prefer the @each loop .

How to add an element to a list

To add an element to a list, we use the list.append() function.

The append() function also takes two arguments. The first argument is the list we want to add an element to, and the second argument is the value we want to add.

$original_list: (value1, value2, ...);

append($original_list, added_value);
// or
$new_list: append($original_list, added_value);

note Sass lists are immutable, which means we cannot dynamically add values to them. When we append a value to a list, it makes a copy of the list instead of changing the original.

note We are allowed to assign the new list to the old list’s variable, overwriting it.

$font-sizes: (14px, 16px, 18px, 20px);
$font-size: append($font-sizes, 22px);

body {
  font-size: nth($font-size, -1);
}

In the example above we add 22px as the fifth value in the list and assign it to a new variable.

body {
  font-size: 22px;
}

How to find an element in a list

Sometimes we need to check if a list contains a specific value and at which index the value is. Sass provides us with the index() function to do this quickly and easily.

This function takes two arguments. The first argument is the list we want to search inside of, and the second argument is the value we want to search for.

If the specified value is inside the list, the function will return its index number. If the value is not in the list, the function will return null .

$list: (value, value, ...);

index($list, value);
// or
$result: index($list, value);

$font-sizes: (14px, 16px, 18px, 20px);

body {
  font-size: nth($font-sizes, index($font-sizes, 20px));
}

Instead of specifying an index number directly to get a certain value, we use the function to search for the value and use the returned index number.

Summary: Points to remember

• A list is a data container that stores multiple values in a table-like structure.
  • Sass lists are immutable, which means their values cannot be changed dynamically.
• Sass provides us with multiple options to define a new list into a variable.
  • Values separated with a comma.
  • Values separated with a space.
  • Values separated with a comma, inside parentheses.
  • Values separated with a space, inside parentheses.
  • Values separated with a space, inside square brackets.
• The indexer is a number that corresponds to a value in the list.
• We use the built-in nth() function to access a value via its indexer.
• We use the built-in append() function to add a value to the end of the list.
  • When a value is added to a list, it doesn’t modify the original list but rather creates a copy.
• To check whether an element exists in a list, and its location in it, we use the index() function.