sass:list

Compatibility:
Dart Sass
since (unreleased)
LibSass
Ruby Sass

Only Dart Sass currently supports loading built-in modules with @use. Users of other implementations must call functions using their global names instead.

list.append($list, $val, $separator: auto)
append($list, $val, $separator: auto) //=> list 

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

If $separator is comma, the returned list is comma-separted. If it’s space, the returned list is space-separated. If it’s auto (the default), the returned list will use the same separator as $list (or space if $list doesn’t have a separator). Other values aren’t allowed.

Note that unlike list.join(), if $val is a list it’s nested within the returned list rather than having all its elements added to the returned list.

SCSS Syntax

@debug list.append(10px 20px, 30px); // 10px 20px 30px
@debug list.append((blue, red), green); // blue, red, green
@debug list.append(10px 20px, 30px 40px); // 10px 20px (30px 40px)
@debug list.append(10px, 20px, $separator: comma); // 10px, 20px
@debug list.append((blue, red), green, $separator: space); // blue red green

Sass Syntax

@debug list.append(10px 20px, 30px)  // 10px 20px 30px
@debug list.append((blue, red), green)  // blue, red, green
@debug list.append(10px 20px, 30px 40px)  // 10px 20px (30px 40px)
@debug list.append(10px, 20px, $separator: comma)  // 10px, 20px
@debug list.append((blue, red), green, $separator: space)  // blue red green
list.index($list, $value)
index($list, $value) //=> number | null 

Returns the index of $value in $list.

If $value doesn’t appear in $list, this returns null. If $value appears multiple times in $list, this returns the index of its first appearance.

SCSS Syntax

@debug list.index(1px solid red, 1px); // 1
@debug list.index(1px solid red, solid); // 2
@debug list.index(1px solid red, dashed); // null

Sass Syntax

@debug list.index(1px solid red, 1px)  // 1
@debug list.index(1px solid red, solid)  // 2
@debug list.index(1px solid red, dashed)  // null
list.is-bracketed($list)
is-bracketed($list) //=> boolean 

Returns whether $list has square brackets.

SCSS Syntax

@debug list.is-bracketed(1px 2px 3px); // false
@debug list.is-bracketed([1px, 2px, 3px]); // true

Sass Syntax

@debug list.is-bracketed(1px 2px 3px)  // false
@debug list.is-bracketed([1px, 2px, 3px])  // true
list.join($list1, $list2, $separator: auto, $bracketed: auto)
join($list1, $list2, $separator: auto, $bracketed: auto) //=> list 

Returns a new list containing the elements of $list1 followed by the elements of $list2.

If $separator is comma, the returned list is comma-separted. If it’s space, the returned list is space-separated. If it’s auto (the default), the returned list will use the same separator as $list1 if it has a separator, or else $list2 if it has a separator, or else space. Other values aren’t allowed.

If $bracketed is true, the returned list has square brackets. If it’s false, the returned list has no brackets. If it’s auto (the default), the returned list will be bracketed if $list1 is. Other values aren’t allowed.

SCSS Syntax

@debug list.join(10px 20px, 30px 40px); // 10px 20px 30px 40px
@debug list.join((blue, red), (#abc, #def)); // blue, red, #abc, #def
@debug list.join(10px, 20px); // 10px 20px
@debug list.join(10px, 20px, $separator: comma); // 10px, 20px
@debug list.join((blue, red), (#abc, #def), $separator: space); // blue red #abc #def
@debug list.join([10px], 20px); // [10px 20px]
@debug list.join(10px, 20px, $bracketed: true); // [10px 20px]

Sass Syntax

@debug list.join(10px 20px, 30px 40px)  // 10px 20px 30px 40px
@debug list.join((blue, red), (#abc, #def))  // blue, red, #abc, #def
@debug list.join(10px, 20px)  // 10px 20px
@debug list.join(10px, 20px, comma)  // 10px, 20px
@debug list.join((blue, red), (#abc, #def), space)  // blue red #abc #def
@debug list.join([10px], 20px)  // [10px 20px]
@debug list.join(10px, 20px, $bracketed: true)  // [10px 20px]
list.length($list)
length($list) //=> number 

Returns the length of $list.

This can also return the number of pairs in a map.

SCSS Syntax

@debug list.length(10px); // 1
@debug list.length(10px 20px 30px); // 3
@debug list.length((width: 10px, height: 20px)); // 2

Sass Syntax

@debug list.length(10px)  // 1
@debug list.length(10px 20px 30px)  // 3
@debug list.length((width: 10px, height: 20px))  // 2
list.separator($list)
list-separator($list) //=> unquoted string 

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

If $list doesn’t have a separator, returns space.

SCSS Syntax

@debug list.separator(1px 2px 3px); // space
@debug list.separator(1px, 2px, 3px); // comma
@debug list.separator('Helvetica'); // space
@debug list.separator(()); // space

Sass Syntax

@debug list.separator(1px 2px 3px)  // space
@debug list.separator(1px, 2px, 3px)  // comma
@debug list.separator('Helvetica')  // space
@debug list.separator(())  // 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.

SCSS Syntax

@debug list.nth(10px 12px 16px, 2); // 12px
@debug list.nth([line1, line2, line3], -1); // line3

Sass Syntax

@debug list.nth(10px 12px 16px, 2)  // 12px
@debug list.nth([line1, line2, line3], -1)  // line3
list.set-nth($list, $n, $value)
set-nth($list, $n, $value) //=> list 

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.

SCSS Syntax

@debug list.set-nth(10px 20px 30px, 1, 2em); // 2em 20px 30px
@debug list.set-nth(10px 20px 30px, -1, 8em); // 10px, 20px, 8em
@debug list.set-nth((Helvetica, Arial, sans-serif), 3, Roboto); // Helvetica, Arial, Roboto

Sass Syntax

@debug list.set-nth(10px 20px 30px, 1, 2em); // 2em 20px 30px
@debug list.set-nth(10px 20px 30px, -1, 8em); // 10px, 20px, 8em
@debug list.set-nth((Helvetica, Arial, sans-serif), 3, Roboto); // Helvetica, Arial, Roboto
list.zip($lists...)
zip($lists...) //=> list 

Combines every list in $lists 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.

SCSS Syntax

@debug list.zip(10px 50px 100px, short mid long); // 10px short, 50px mid, 100px long
@debug list.zip(10px 50px 100px, short mid); // 10px short, 50px mid

Sass Syntax

@debug list.zip(10px 50px 100px, short mid long)  // 10px short, 50px mid, 100px long
@debug list.zip(10px 50px 100px, short mid)  // 10px short, 50px mid