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. <dl> <dt><code>compare-string ( $first-item, $second-item )</code></dt> <dd>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.</dd> <dt><code>compare-string-desc ( $first-item, $second-item )</code><dt> <dd>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.</dd> </dl>
compare-numeric ()
,compare-numeric-desc ()
Returns a function reference to the numeric comparison method used by the sort function. <dl> <dt><code>compare-numeric ( $first-item, $second-item [, $center] )</code></dt> <dd>Used to compare two list items as numbers in ascending order. All non-numeric items are shifted right.</dd> <dt><code>compare-numeric-desc ( $first-item, $second-item [, $center] )</code><dt> <dd>Used to compare two list items as numbers in descending order. All non-numeric items are shifted left.</dd> </dl>
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.