Sass Lists — Complete Guide

Q: How do I make a list empty?

Assign an empty parentheses: `$list: ()`. Check with `list.length($list) == 0`.

DodaTech Updated 2026-06-28 6 min read

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

Sass lists store ordered values for iteration, access, and manipulation using functions from sass:list module for flexible data handling.

What You'll Learn

Creating lists with comma or space separation
Accessing list items with nth()
List iteration with @each
List manipulation (append, join, set-nth)
Checking list properties (length, index)
Nested lists
Using lists for configuration

Why It Matters

Lists group related values for iteration
Configuration data can drive CSS generation
Lists reduce repetition in utility generation
Lists are the foundation for maps

Real-World Use

A font stack is a list of fallback fonts
A breakpoint list drives responsive generation
A spacing scale is a list of values
A component generates variants from a list

flowchart LR
  A[Sass Lists] --> B[Space-separated]
  A --> C[Comma-separated]
  B --> D[$fonts: ...]
  C --> E[$colors: ...]
  D --> F[Iterate with @each]
  E --> F
  F --> G[Generate CSS]

Working with Lists

Code Example: Creating and Accessing Lists

@use 'sass:list';

// Space-separated list (default)
$fonts: 'Inter' 'Helvetica' Arial sans-serif;

// Comma-separated list
$colors: #0066CC, #28a745, #dc3545, #ffc107;

// Mixed
$values: 10px 20px, 30px 40px;  // Two comma-separated space-separated lists

// Accessing items (1-indexed)
$first-font: list.nth($fonts, 1);      // 'Inter'
$last-font: list.nth($fonts, -1);      // sans-serif
$third-color: list.nth($colors, 3);    // #dc3545

// List length
$font-count: list.length($fonts);      // 4
$color-count: list.length($colors);    // 4

// Find index of a value
$index: list.index($colors, #28a745);  // 2

// Check if list is empty
$empty: ();
$is-empty: list.length($empty) == 0;   // true

// Usage in properties
.element {
    font-family: $fonts;                // font-family: 'Inter', 'Helvetica', Arial, sans-serif;
    box-shadow: 0 2px 4px rgba(0,0,0,0.1), 0 4px 8px rgba(0,0,0,0.05);
    // This is a comma-separated list of shadows
}

Expected output: Lists are 1-indexed. nth() retrieves items by position. length() returns the count. index() finds the position of a value. Lists in property values are expanded correctly with commas.

Code Example: List Manipulation

@use 'sass:list';

// Append to a list
$sizes: 10px 20px 30px;
$sizes: list.append($sizes, 40px);           // 10px 20px 30px 40px
$sizes: list.append($sizes, 50px, comma);    // 10px, 20px, 30px, 40px, 50px (comma!)

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

// Join with separator
$zipped: list.zip(10px 20px 30px, #ccc #ddd #eee);
// Returns: 10px #ccc, 20px #ddd, 30px #eee

// Set value at position
$colors: #0066CC #28a745 #dc3545;
$colors: list.set-nth($colors, 2, #ff6600);  // #0066CC #ff6600 #dc3545

// Remove from list (no built-in, use @each)
@function list-remove($list, $index) {
    $result: ();
    @for $i from 1 through list.length($list) {
        @if $i != $index {
            $result: list.append($result, list.nth($list, $i), list.separator($list));
        }
    }
    @return $result;
}

$colors: list-remove($colors, 1);            // #ff6600 #dc3545

// Check separator type
$sep: list.separator($fonts);  // space
$sep2: list.separator($colors); // space

Expected output: append() adds items. join() combines lists. set-nth() replaces items at a position. Custom functions can extend list manipulation.

Code Example: Iterating Lists

@use 'sass:list';

// Basic @each
$breakpoints: 480px 768px 1024px 1280px;

@each $width in $breakpoints {
    @media (min-width: $width) {
        .container {
            max-width: $width - 40px;
        }
    }
}

// @each with index
$sizes: 10px 20px 30px 40px;

@each $size in $sizes {
    $i: list.index($sizes, $size);
    .size-#{$i} {
        font-size: $size;
    }
}

// Alternative: @for with index (more reliable for duplicate values)
@for $i from 1 through list.length($sizes) {
    .size-#{$i} {
        font-size: list.nth($sizes, $i);
    }
}

// Multiple lists iteration (zip)
$properties: 'margin-top' 'margin-right' 'margin-bottom' 'margin-left';
$values: 10px 20px 10px 20px;

@for $i from 1 through list.length($properties) {
    .spacing-#{$i} {
        #{list.nth($properties, $i)}: list.nth($values, $i);
    }
}

// List of lists
$buttons: (
    ('primary', #0066CC, #fff),
    ('success', #28a745, #fff),
    ('danger', #dc3545, #fff)
);

@each $btn in $buttons {
    $name: list.nth($btn, 1);
    $bg: list.nth($btn, 2);
    $color: list.nth($btn, 3);

    .btn-#{$name} {
        background: $bg;
        color: $color;

        &:hover {
            background: darken($bg, 10%);
        }
    }
}

Expected output: Lists are iterated with @each or @for. List of lists enables structured data for component generation.

Code Example: Lists for Configuration

@use 'sass:list';
@use 'sass:math';

// Button variant configuration
$button-variants: (
    'primary'   #0066CC #fff,
    'secondary' #6c757d #fff,
    'success'   #28a745 #fff,
    'danger'    #dc3545 #fff,
    'warning'   #ffc107 #333,
    'info'      #17a2b8 #fff,
    'light'     #f8f9fa #333,
    'dark'      #343a40 #fff
);

@each $variant in $button-variants {
    $name: list.nth($variant, 1);
    $bg: list.nth($variant, 2);
    $color: list.nth($variant, 3);
    $hover-bg: darken($bg, 10%);

    .btn-#{$name} {
        background: $bg;
        color: $color;

        &:hover {
            background: $hover-bg;
        }

        &:focus-visible {
            outline: 3px solid rgba($bg, 0.4);
        }
    }

    .btn-outline-#{$name} {
        background: transparent;
        color: $bg;
        border: 2px solid $bg;

        &:hover {
            background: $bg;
            color: $color;
        }
    }
}

// Responsive font sizes
$font-sizes: (
    (h1, 2.5rem, 1.2),
    (h2, 2rem, 1.3),
    (h3, 1.75rem, 1.4),
    (h4, 1.5rem, 1.5),
    (h5, 1.25rem, 1.6),
    (h6, 1rem, 1.6)
);

@each $size in $font-sizes {
    $tag: list.nth($size, 1);
    $min: list.nth($size, 2);
    $lh: list.nth($size, 3);

    #{$tag} {
        font-size: clamp(#{$min}, #{$min} + 1vw, #{$min * 1.5});
        line-height: $lh;
    }
}

// Z-index tokens
$z-layers: 'modal' 1000 'overlay' 900 'dropdown' 800 'header' 700 'default' 1;

@function z($name) {
    $length: list.length($z-layers);
    @for $i from 1 through $length {
        @if list.nth($z-layers, $i) == $name {
            @return list.nth($z-layers, $i + 1);
        }
    }
    @return 0;
}

.modal { z-index: z('modal'); }

Expected output: Lists of lists create structured configuration for generating button variants, heading sizes, and z-index tokens. Each variant's data is colocated in the list.

Common Mistakes

Forgetting lists are 1-indexed — list.nth($list, 0) causes an error. The first item is at index 1.
Mixing space and comma separators — list.append($list, $value) defaults to space separator. Use the $separator parameter for commas.
Modifying lists during iteration — Lists are immutable in Sass. Operations return new lists. Assign the result to a variable.
Using @each with duplicate values — list.index() returns the first occurrence. Use @for with index for reliable position tracking.
Not checking list length before access — Accessing an out-of-bounds index causes an error. Use list.length() for bounds checking.
Assuming lists are mutable — All list functions return new lists. The original list is unchanged.
Overusing lists when maps are clearer — Maps (key-value pairs) are often more readable than lists of lists for structured data.

Practice Questions

Are Sass lists 0-indexed or 1-indexed? 1-indexed. The first item is at position 1.
How do you find the position of a value in a list? list.index($list, $value) returns the position or null.
What is the difference between space-separated and comma-separated lists? Space-separated: "a b c". Comma-separated: "a, b, c". The separator affects how lists are output in CSS.
How do you add an item to a list? list.append($list, $value, $separator) returns a new list with the value appended.

FAQ

When would I use a list vs a map?

Use lists for ordered values without keys (font stacks, breakpoints). Use maps for key-value pairs (color names to values).

Can a list contain other lists?

Yes. Nested lists enable structured data: ((a 1), (b 2), (c 3)). Use list.nth() to access sub-lists.

How do I make a list empty?

Assign an empty parentheses: $list: (). Check with list.length($list) == 0.

Mini Project

Build a complete button and label system using list configuration. Create a $variants list of lists (name, bg, text, hover-effect). Use @each to generate .btn-{name} (filled), .btn-outline-{name} (outlined), .btn-ghost-{name} (ghost), and .label-{name} (small label) components. Use list.append() to add a new variant dynamically. Use list.index() to create a function that looks up variant properties. Use list.nth() with @for to generate numbered utility classes (mt-1 through mt-8). Demonstrate that the entire component system is driven by the $variants list.

What's Next

Continue with Lesson 13: Sass Maps to learn key-value data structures in Sass.

← Previous Sass Color Functions — Complete Guide Next → Sass Maps — Complete Guide

Built by the developers of DodaTech

Doda Browser, DodaZIP & Durga Antivirus Pro

Home Browse Css Preprocessors