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 |