sass-list

sass-list

This Sass module provides more advanced list functions.

Install

Requires

• Dart Sass: >=1.33.0

Install the package:

npm install sass-list

Use the package like any other Sass module:

@use 'sass-list';

Depending on your setup, you may need to configure node_modules as include path:

const sass = require('sass');

sass.render({
  file: scss_filename,
  includePaths: ['node_modules']
});

Public API

Functions

concat ( $values... [, $separator] [, $bracketed] ) Merges two or more lists into a new list. distinct ( $list [, $separator] ) Creates a new list with all distinct items from a list. empty ( [$separator] [, $bracketed] [, $list] ) Creates an empty list with the specified characteristics or the characteristics of the specified list. every ( $list, $predicate [, $args...] ) Tests whether all items in a list satisfy the test implemented by the specified function. filter ( $list, $predicate [, $separator] [, $args...] ) Creates a new list with all item from a list that satisfy the test implemented by the specified function. find ( $list, $predicate [, $args...] ) Returns the value of the first element from a list that satisfies the test implemented by the specified function. find-nth ( $list, $predicate [, $args...] ) Returns the index of the first item from a list that satisfies the test implemented by the specified function; otherwise, 0 is returned, indicating no item satisfies the test. flat ( $list [, $depth] [, $separator] [, $bracketed] ) Creates a new list with all sub-list items concatenated into it recursively up to a specified depth. includes ( $list, $value [, $start-at] ) Determines whether a list includes a certain value among its items, returning true or false as appropriate. index ( $list, $value [, $start-at] ) Returns the first index at which a specified item can be found in a list; otherwise, 0 is returned, indicating the item is not present. insert-nth ( $list, $index, $value [, $separator] ) Returns a copy of a list with the specified value inserted into the list at a given index. join ( $list [, $glue] ) Concatenates all of the items in a list to a string, separated by the list's separator or a specified glue string. If the list has only one item, then that item will be returned without using the glue. last-index ( $list, $value [, $start-at] ) Returns the last index at which a specified item can be found in a list; otherwise, 0 is returned, indicating the item is not present. The list is searched backwards, starting at a given index when specified. map ( $list, $transformer [, $separator] [, $bracketed] [, $args...] ) Creates a new list populated with the results of calling a specified function on every item in a list. prepend ( $list, $value [, $separator] ) Returns a copy of a list with the specified value added to the beginning. reduce ( $list, $transformer [, $initial-value] [, $args...] ) Reduces a list to a single value as the product of calling a specified function on every item in a list. reduce-right ( $list, $transformer [, $initial-value] [, $args...] ) Reduces a list to a single value as the product of calling a specified function on every item in a list, starting with the last item to the first. remove ( $list, $value [, $separator] ) Returns a copy of a list without the specified value. remove-nth ( $list, $index [, $separator] ) Returns a copy of a list without the value at a given index. replace ( $list, $value, $replacement [, $separator] ) Returns a copy of a list with all occurrences of the specified value replaced by the specified replacement. reverse ( $list [, $separator] ) Reverses a list in place. The first item becomes the last, and the last item becomes the first. set-nth ( $list, $index, $value [, $separator] ) Returns a copy of a list with the value at the given index replaced with the specified value. slice ( $list, $start-at [, $end-at] [, $separator] ) Extracts a portion of a list into a new list selected from a starting index through a ending index. some ( $list, $predicate [, $args...] ) Tests whether at least one item in a list satisfies the test implemented by the specified function. sort ( $list [, $compare] [, $center] [, $separator] ) Sorts the items of a list in place. The default sort order is ascending, built upon converting the items into strings, then comparing their sequences of UTF-16 code units values. to-string ( $list ) Returns a string representing the specified list and its items.

Don't see the function you're looking for? Request a new feature describing a use case.

Comparison Methods

compare-string (), compare-string-desc () Returns a function reference to the string comparison method used by the sort function. compare-string ( $first-item, $second-item ) Used to compare two list items by converting them to strings, then comparing the value's sequences of UTF-16 code units values in ascending order. All null items are shifted right. compare-string-desc ( $first-item, $second-item ) Used to compare two list items by converting them to strings, then comparing the value's sequences of UTF-16 code units values in descending order. All null items are shifted left. compare-numeric (), compare-numeric-desc () Returns a function reference to the numeric comparison method used by the sort function. compare-numeric ( $first-item, $second-item [, $center] ) Used to compare two list items as numbers in ascending order. All non-numeric items are shifted right. compare-numeric-desc ( $first-item, $second-item [, $center] ) Used to compare two list items as numbers in descending order. All non-numeric items are shifted left.

More information on comparison logic and reference functions.

Combined API

In order to avoid constantly declaring both the native 'sass:list' module and this library, the combined API has been added which merges the two.

// Rather than using both modules separately...
@use 'sass-list';
@use 'sass:list';

// ...this statement will accomplish the same thing.
@use 'sass-list/list';

Note: Since their functionality is enhanced by this library, the combined API hides the native list.index(), list.join() and list.set-nth() functions.

Further Reading

1. Comparison Logic
2. Reference Functions
3. List Configuration Modifiers