SASS/SCSS #19: Built-in modules

Welcome back to series about SASS/SCSS. If you love this topic, this is a link for you follow other articles. Series about SASS/SCSS

In this article, we will discuss “sass:list”. To better understand this part, please read the article about list. Lists in SASS/SCSS

Table of contents:

Overview
Functions in Module Lists

Let’s go to the content!

Overview

If you master Lists in Sass, you can already do a lot. You may wonder, what about Maps, maybe Maps is not important. There is a fun fact that Maps traverses’ elements similar to Lists. Maps have key/value pairs count as a list container a two-element list.

// index.scss

// Maps ("primary": 1, "secondary": 2);

// => (primary 1, secondary 2)

You can get how Maps works like Lists. So, let's take a look at what functions in Lists will have?

list.append($list, $val, $separator) – append($list, $val, $separator)

Returns a copy of list with $val added to the end.

$separator is comma, space, or auto.

First we will see how list.append() works.

// index.scss

@use 'sass:list';

$list1: (1, 2, 3, 4);

@debug list.append($list1, 4); // => 1, 2, 3, 4, 4

@debug list.append(10px 20px, 30px, $separator: comma); // 10px, 20px, 30px

@debug list.append($list1, 5, $separator: space); // 1 2 3 4 5

@debug list.append($list1, 5, $separator: auto); // 1, 2, 3, 4, 5

We have list.append() which will take 3 arguments. The first is the initial list, followed by the value to be added to that list, which will be added at the end of the list. Finally, we have $separator with the values of comma, space, or auto, this will define how the new list will be structured.

There are a few things when using list.append() you need to be aware of. If you use list.append() alone without @debug you will immediately get an error.

// index.scss

@use 'sass:list';

$list1: (1, 2, 3, 4);

list.append($list1, 5);

// => Error: expected "{".

Next if you put more than 3 arguments in list.append(), you will immediately get an error as well. You will likely get this error in cases where you define a list with a comma. separator.

// index.scss

@use 'sass:list';

$list1: (1, 2, 3, 4);

list.append((1, 2, 3, 4), 5);

// => Error: expected "{".

Finally, the list after being appended is a copy of the original list. If you change one of the lists, the value in the other list will not be changed.

// index.scss

@use 'sass:list';

$list1: (1, 2, 3, 4);

$list2: list.append($list1, 4);

@debug $list1; // => 1, 2, 3, 4

@debug list.append($list1, 5); // => 1, 2, 3, 4, 5

@debug $list2; // => 1, 2, 3, 4, 4

Both lists are completely independent of each other. Finally, if you don't use $separator the default is auto. And the newly created list will be list with comma separator.

List.index($list, $value) - index($list, $value)

The function list.index() is completely easy to use. With the first argument being a list and the second argument being the value we want to check. This function will return the order of $value that is in $list.

// index.scss

@use 'sass:list';

$list1: (4, 3, 2, 1);

@debug list.index($list1, 1); // => 4

@debug list.index($list1, 4); // => 1

@debug list.index($list1, 5); // => 5

You need to note a few points as follows: index of list will start at 1 and end with list.length(). If $value is not in $list, the result we get will be null.

List.is-bracketed($list) – is-bracketed($list)

The function list.is-bracketed($list) is very simple. This function will check if $list is a list has square brackets or not. And of course, the return result will be Booleans.

// index.scss

@use 'sass:list';

$list1: (4, 3, 2, 1);

$list2: [1, 2, 3, 4];

@debug list.is-bracketed($list1); // => false

@debug list.is-bracketed($list2); // => true

List.join($list1, $list2, $separator: auto, $bracketed: auto) – join($list1, list2, $separator: auto, $bracketd: auto)

If we have list.append() is the function used to add elements in a given list. In case if we want to join two lists together then we need another function called join() function. The function will return a new list containing the elements of $list1 followed by the elements of $list2.

// index.scss

@use 'sass:list';

$list1: (4, 3, 2, 1);

$list2: [1,2,3,4];

@debug list.join($list1, $list2, $separator: space, $bracketed: false);

// => 4 3 2 1 1 2 3 4

@debug list.join($list2, $list1, $separator: comma, $bracketed: true);

// => [1, 2, 3, 4, 4, 3, 2, 1]

You can see that the result will depend on where we place the lists in the join() function. Besides, we also have arguments as $separator with values of space, comma, or auto. $bracketed with a value of Booleans true or Boolean false, which determines whether the return result is a list has square bracket or not.

List.length($list) – length($list)

Returns the length of $list.

// index.scss

@use 'sass:list';

$list1: (4, 3, 2, 1, 5, 6);

$list2: (4, 3, 2, 6);

@debug list.length($list1); // => 6

@debug list.length($list2); // => 4

One cool thing is that Maps can be browsed as Lists. Our use of list.length() for Maps can also return the number of pairs in a map.

// index.scss

@use 'sass:list';

$map1: (1: 1, 2: 2, 3: 3);

$map2: (4: 4, 5: 5, 6: 6, 7: 7, 8: 8);

@debug list.length($map1); // => 3

@debug list.length($map2); // => 5

List.separator($list) – list-separator($list)

Returns the name of separator used by $list either space, comma, or slash.

// index.scss

@use 'sass:list';

$list1: (1, 2, 3);

$list2: (4 5 6);

$list3: (7);

$list4: (());

@debug list.separator($list1); // => comma

@debug list.separator($list2); // => space

@debug list.separator($list3); // => space

@debug list.separator($list4); // => space

If $list has one or zero element, return space.

List.nth($list, $n) – nth($list, $n)

Returns the element of $list at index $n.

If $n is negative, it counts from the end of $list. Throws an error if there is no element at index $n.

// index.scss

@use 'sass:list';

$list1: (1, 2, 3);

@debug list.nth($list1, 1); // => 1

@debug list.nth($list1, -1); // => 3

@debug list.nth($list1, -3); // => 1

@debug list.nth($list1, 0);

// => Error: $n: List index may not be 0.

@debug list.nth($list1, 4);

// => Error: $n: Invalid index 4 for a list with 3 elements.

As can be seen, we can completely set $n as a negative number. And one caveat is that $n cannot be zero. If $n = zero we will get error.

List.set-nth($list, $n, $value) – set-nth($list, $n, $value)

Returns a copy of $list with the element at index $n replaced with $value.

If $n is negative, it counts from the end of $list. Throws an error if there is no existing element at index $n.

// index.scss

@use 'sass:list';

$list1: (1, 2, 3);

@debug list.set-nth($list1, 1, 9); // => 9, 2, 3

@debug list.set-nth($list1, -1, 8); // => 1, 2, 8

@debug list.set-nth($list1, 4, 7);

// => Error: $n: Invalid index 4 for a list with 3 elements.

$n will start at 1 and end with $list.length. Besides, you will see that every time we use list.set-nth() we will create a new list, the original list will not be affected.

List.zip($list…) – zip($list…)

Combines every list in $list into a single list of sub-lists.

Each element in the returned list contains all the elements at that position in $lists. The returned list is as long as the shortest list in $lists.

The returned list is always comma-separated and the sub-lists are always space-separated.

// index.scss

@use 'sass:list';

$list1: (1, 2, 3);

$list2: (4, 5, 6);

$list3: (7, 8, 9);

@debug list.zip($list1, $list2, $list3);

// => 1 4 7, 2 5 8, 3 6 9

Conclusion

The functions introduced above cannot be used independently at all. We can only use it when combined with @debug or in another function. At the same time, you have also learned about the functions in the module list. From these functions you can customize your problem according to each specific case.

If you have any ideas, feel free to comment below. Thank you for joining with me. Having a good day!