Sass Lists

Lists are Sass's way of storing an ordered collection of values, font stacks, breakpoint names, or box-shadow layers. This lesson explains list syntax, indexing, and the sass:list module's functions for working with them.

What Is a Sass List?

A list is an ordered sequence of values separated by either commas or spaces. Many CSS values are already lists in disguise, a font stack, a multi-layer box-shadow, or a transition with multiple properties, and Sass lets you build and manipulate them programmatically.

$font-stack: "Helvetica Neue", Arial, sans-serif; // comma-separated list
$border: 1px solid #cbd5e1;                        // space-separated list

.text {
  font-family: $font-stack;
}

Both examples are valid Sass lists; the separator (comma or space) is preserved when the list is output as CSS.

List Syntax and Indexing

@use 'sass:list';

$sizes: 8px, 16px, 24px;
list.nth($sizes, 1);   // => 8px, 1-based indexing
list.length($sizes);   // => 3

Lists can be comma-separated (a, b, c) or space-separated (a b c).
Sass list indexing is 1-based, not 0-based, list.nth($list, 1) returns the first item.
Negative indexes count from the end: list.nth($list, -1) returns the last item.
Lists can be nested, a list of lists, useful for representing rows of values like breakpoints and their labels.

Sass Lists Cheatsheet

The sass:list module functions you'll use most often.

Function	Example	Result
`list.length()`	`list.length((sm, md, lg))`	`3`
`list.nth()`	`list.nth((sm, md, lg), 2)`	`md`
`list.nth()` negative	`list.nth((sm, md, lg), -1)`	`lg`
`list.append()`	`list.append((sm, md), lg)`	`sm, md, lg`
`list.join()`	`list.join((a, b), (c, d))`	`a, b, c, d`
`list.index()`	`list.index((sm, md, lg), md)`	`2`
`list.separator()`	`list.separator((a, b))`	`comma`

Iterating a List With @each

The most common thing you'll do with a list is loop over it to generate a rule per item, covered in depth in the @each Loop lesson, but shown briefly here to demonstrate why lists matter.

$spacers: 4px, 8px, 16px, 32px;

@each $space in $spacers {
  .m-#{$space} {
    margin: $space;
  }
}

Generates .m-4px, .m-8px, .m-16px, and .m-32px rules, one per list item.

Building and Transforming Lists

sass:list functions let you build up a list dynamically, append items, join two lists together, or find where a value sits within a list, without hardcoding every possible combination by hand.

@use 'sass:list';

$base-shadows: 0 1px 2px rgba(0, 0, 0, 0.05);
$extra-shadow: 0 8px 16px rgba(0, 0, 0, 0.1);

$all-shadows: list.append($base-shadows, $extra-shadow, comma);

Nested Lists

A list can contain other lists, useful for representing structured data like a set of named breakpoints with their pixel values, without needing a full map.

$breakpoints: (sm 576px), (md 768px), (lg 992px);

@each $bp in $breakpoints {
  $name: list.nth($bp, 1);
  $size: list.nth($bp, 2);
  // use $name and $size...
}

For most real projects, a map (covered next) is often clearer than a nested list for this exact use case.

Common Mistakes

Forgetting Sass lists are 1-indexed, not 0-indexed, a very common source of off-by-one bugs for developers coming from JavaScript.
Not specifying the separator when building a list with list.append(), which can silently produce a space-separated list when a comma-separated one was intended.
Using a nested list where a map would be clearer and less error-prone, especially for named key-value data.
Assuming list functions mutate the original list in place; Sass lists are immutable, every list function returns a new list.

Key Takeaways

Sass lists store ordered values, separated by commas or spaces, and can be nested.
List indexing is 1-based; negative indexes count from the end of the list.
The sass:list module provides functions to inspect, build, and transform lists.
For named key-value data, a map is usually clearer than a nested list.

Pro Tip

Reach for @each over manual indexing whenever possible, looping with @each $item in $list is more readable and less error-prone than manually tracking an index with list.nth() in a @for loop.