Sass: List Functions
The Sass list functions allow you to interrogate, manipulate and combine lists in expected ways.
Sass lists are immutable (they cannot be changed).
So all the list functions that return a list, join() for example, return a new list. They do not alter the original list.
Like the string functions, the only tricky thing about Sass lists are that they are one-based rather than zero-based.
Sass List Functions
The following table lists all list functions in Sass:
| Function | Description | Example | 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 |