sass:list module

Introduction

The sass:list module helps you work with lists in Sass easily. It gives you tools to add, remove, or check items in lists without mistakes.

You want to add a color to a list of theme colors.

You need to check if a font is already in your font stack list.

You want to get the length of a list of spacing sizes.

You want to join two lists of CSS classes together.

You want to remove a specific item from a list of breakpoints.

Syntax

SASS

@use "sass:list";

// Example functions:
list.append($list, $value, $separator: auto)
list.length($list)
list.index($list, $value)
list.join($list1, $list2, $separator: auto)
list.remove($list, $value)
list.nth($list, $index)

Always @use "sass:list"; to access these functions.

Lists in Sass can be comma-separated or space-separated; some functions let you control this with $separator.

Examples

Adds yellow to the end of the $colors list.

SASS

@use "sass:list";

$colors: red, green, blue;
$new-colors: list.append($colors, yellow);
// $new-colors is red, green, blue, yellow

Finds the position of Helvetica in the $fonts list.

SASS

@use "sass:list";

$fonts: Arial, Helvetica, sans-serif;
$index: list.index($fonts, Helvetica);
// $index is 2

Counts how many items are in the $spacing list.

SASS

@use "sass:list";

$spacing: 0.5rem 1rem 2rem;
$length: list.length($spacing);
// $length is 3

Joins two lists into one.

SASS

@use "sass:list";

$list1: a, b, c;
$list2: d, e;
$joined: list.join($list1, $list2);
// $joined is a, b, c, d, e

Sample Program

This Sass code shows how to use the sass:list module to get the length of a list, add an item, remove an item, and get an item by position. The results are stored in CSS custom properties so you can see them in the browser.

SASS

@use "sass:list";

$breakpoints: mobile, tablet, desktop;

// Print original list length
$original-length: list.length($breakpoints);

// Add a new breakpoint
$new-breakpoints: list.append($breakpoints, widescreen);

// Remove the breakpoint 'tablet'
$updated-breakpoints: list.remove($new-breakpoints, tablet);

// Get the first breakpoint
$first-breakpoint: list.nth($updated-breakpoints, 1);

// Output styles to see results
body {
  --original-length: #{$original-length};
  --new-list: #{list.join($new-breakpoints, (), ", ")};
  --updated-list: #{list.join($updated-breakpoints, (), ", ")};
  --first-breakpoint: #{$first-breakpoint};
}

Important Notes

The list.length() function runs in constant time, so it is very fast.

Remember that list indexes start at 1, not 0.

Use list.remove() carefully because removing an item shifts the positions of later items.

Summary

The sass:list module helps manage lists easily in Sass.

You can add, remove, find, and join list items safely.

Always use @use "sass:list"; to access these functions.