Sass List Functions — Manipulating Lists and Arrays

In this tutorial, you will learn about Sass List Functions. We cover key concepts, practical examples, and best practices to help you master this topic.

Sass list functions from the sass:list module allow accessing items by index, appending, joining, splitting, and checking list properties for dynamic value management.

What You'll Learn

You will learn the essential list functions: nth, append, join, index, length, and separator management for building style lists.

Why It Matters

Lists manage groups of CSS values. DodaTech uses lists for font stacks, transition properties, box-shadow layers, and gradient stops.

Real-World Use

Durga Antivirus Pro uses list functions to manage animation keyframe stops and generate multi-layered box shadows from configuration lists.

flowchart LR
    A[Math Functions] --> B[List Functions]
    B --> C[Access]
    B --> D[Modify]
    B --> E[Join/Split]
    B --> F[Examine]
    style B fill:#c69,stroke:#c69,color:#fff
    style C fill:#22c55e,stroke:#16a34a,color:#fff

Accessing Items

@use "sass:list";

$fonts: ("Inter", "Roboto", "sans-serif");

.first {
  font-family: list.nth($fonts, 1); // "Inter"
}

.last {
  font-family: list.nth($fonts, -1); // "sans-serif" (negative index)
}

// Check length
$count: list.length($fonts); // 3

// Check if list contains a value (returns index or null)
$index: list.index($fonts, "Roboto"); // 2

Expected output: List values accessed by position.

Modifying Lists

@use "sass:list";

$colors: ("red", "green", "blue");

// Append a value
$colors: list.append($colors, "yellow");
// ("red", "green", "blue", "yellow")

// Prepend a value
$colors: list.join(("orange"), $colors);
// ("orange", "red", "green", "blue", "yellow")

// Set a value at index
$colors: list.set-nth($colors, 2, "purple");
// ("orange", "purple", "green", "blue", "yellow")

// Remove separators (makes space-separated)
$list: ("a", "b", "c");
$spaced: list.separator($list); // comma

Expected output: Modified lists with items added, replaced, and checked.

Joining Lists

@use "sass:list";

$list1: (10px, 20px);
$list2: (30px, 40px);

// Join with comma separator
$joined: list.join($list1, $list2, $separator: comma);
// (10px, 20px, 30px, 40px)

// Join with space separator
$spaced: list.join($list1, $list2, $separator: space);
// (10px 20px 30px 40px)

// Using in CSS
.padding {
  padding: $spaced; // 10px 20px 30px 40px
}

Expected output: Joined lists with specified separators used as CSS values.

Splitting and Separators

@use "sass:list";

// Check separator type
$comma-list: ("a", "b");
$space-list: 10px 20px 30px;

.comma-sep {
  content: list.separator($comma-list) + ""; // "comma"
}

.space-sep {
  content: list.separator($space-list) + ""; // "space"
}

// Check if space/comma separated
.is-space {
  content: list.is-space-separated($space-list) + ""; // true
}

.is-comma {
  content: list.is-comma-separated($space-list) + ""; // false
}

Expected output: Separator type detection for list handling.

Practical: Multi-Value Properties

@use "sass:list";

// Build box-shadow from a list
$shadows: (
  (0 1px 3px rgba(0,0,0,0.12)),
  (0 1px 2px rgba(0,0,0,0.06))
);

.card {
  box-shadow: $shadows;
}

// Build transition from component lists
$properties: ("opacity", "transform");
$durations: (0.2s, 0.3s);

@function build-transition($props, $durs) {
  $result: ();
  @each $prop in $props {
    $index: list.index($props, $prop);
    $result: list.append($result, $prop + " " + list.nth($durs, $index), $separator: comma);
  }
  @return $result;
}

.element {
  transition: build-transition($properties, $durations);
  // opacity 0.2s, transform 0.3s
}

Expected output: Multi-value CSS properties built from configuration lists.

List from Map Values

@use "sass:list";
@use "sass:map";

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

// Get all breakpoint values as a list
$values: map.values($breakpoints);
// 576px, 768px, 992px

// Use in a list of media queries
@each $name, $value in $breakpoints {
  @media (min-width: $value) {
    .show-#{$name} { display: block; }
  }
}

Expected output: Values extracted from maps and used to generate utility classes.

Common Mistakes

1. Zero-Based Index Assumption

Sass lists are 1-indexed. nth($list, 0) returns an error. First item is nth($list, 1).

2. Immutable Operations

list.append returns a new list. The original is unchanged. Assign the result to a variable.

3. Separator Mismatch

Joining comma and space lists can produce unexpected separators. Specify the separator explicitly.

4. Nested List Confusion

Lists can contain other lists: ((1, 2), (3, 4)). nth on the outer list returns inner lists.

5. Empty List Operations

Some functions behave differently with empty lists. Check length before accessing items.

Practice Questions

1. How do you get the first item in a list? list.nth($list, 1) returns the first item (lists are 1-indexed).

2. How do you add an item to the end of a list? list.append($list, $item) returns a new list with the item appended.

3. How do you combine two lists? list.join($list1, $list2) returns a combined list.

4. How do you find the index of a value in a list? list.index($list, $value) returns the index or null.

5. What is the default separator for list.append? Space separator by default. Use $separator: comma for comma-separated.

Challenge

Build a box-shadow generator that accepts a list of shadow configurations (each shadow is a sub-list of values) and outputs the combined box-shadow property. Also create a transition Builder that pairs property names with durations.

FAQ

Mini Project

Create a gradient generator using list functions. Accept a list of color stops and generate a linear-gradient value. Add a function that reverses the list for reverse gradients. Build a component that uses both forward and reverse gradients.

What's Next

Learn Sass Map Functions for key-value data. Then explore Sass Extend for selector inheritance.