The Sass list functions allow you to interrogate, manipulate and combine lists in expected ways. The lists can be specified using any of the options described in the SassScript chapter, but you'll need to surround them with parentheses to make it clear that the list is a single argument.
The list functions are used to access values in a list, combine lists, and add items to lists.
Sass lists are immutable (they cannot change). So, the list functions that return a list, will return a new list, and not change the original list. Sass lists are 1-based. The first list item in a list is at index 1, not 0.
The following table lists all list functions in Sass:
| Function | Description | Examples | Result |
|---|---|---|---|
| length($list) | Returns the number of elements in a list | length(1 2 3) | 3 |
| nth($list, $n) | Returns the nth element in a list | nth(1 2 3, 2) | 2 |
| set-nth($list, $n, $value) | Sets the nth element in a list to the value supplied | set-nth(1 2 3, 2, 5) | (1 5 3) |
| join($list1, $list2, [$separator]) | Appends $list2 to the end of $list1. The $separator argument can contain the values comma, space or auto. The auto value, which is the default, will use the separator in the first list. | join(1 2 3, 4 5 6) | (1 2 3 4 5 6) |
| join((1, 2, 3), (4 5 6), auto) | (1, 2, 3, 4, 5, 6) | ||
| join((1, 2, 3), (4 5 6), space) | (1 2 3 4 5 6) | ||
| append($list1, $val, [$separator]) | Appends a single value to the end of a list. If a $separator argument is provided (the default is auto), the entire list the function returns will use that separator | append((1, 2, 3), 4) | (1, 2, 3, 4) |
| append((1, 2, 3), 4, space) | (1 2 3 4) | ||
| zip($lists) | Interleaves the values of the lists provided into a single multi-dimensional list | zip((red, green, blue), (10px, 15px, 5px)) | ((#ff0000 10px), (#00ff00 15px), (#0000ff 5px)) |
| index($list, $value) | Returns the element at the index position specified by $value | index((1 2 3), 2) | 2 |
| list-separator($list) | Returns the name of the separator used in a list as a string | list-separator((1, 2, 3)) | "comma" |
| list-separator((1 2 3)) | "space |
