Chapter 12: Sass List

Sass List Functions — the tools from the sass:list module. Lists are one of Sass’s most powerful data structures, and mastering list functions lets you build flexible, scalable design systems (think spacing scales, breakpoints, color palettes, component variants, etc.).

In 2026 (Dart Sass ~1.97+), you must load the module explicitly with @use ‘sass:list’; — old global names like append() still work but throw deprecation warnings in recent versions. We’ll use the modern module style in every example.

1. Quick Refresher: What is a List in Sass?

A list is an ordered collection of values (separated by spaces or commas, optionally wrapped in () or []).

• Lists can be nested (lists of lists = maps alternative)
• They can have separators: space (default for most), comma, or none (slash-separated rare)
• Bracketed or unbracketed — matters for output in some cases

All list functions return new lists — Sass lists are immutable (great for avoiding bugs).

2. Loading the Module (Always!)

3. The Core sass:list Functions (2026 – Full Practical Set)

Here are the most useful ones with examples and real-world use cases.

A. list.length($list) / length($list)

→ Number of items in the list

Use case: Loop limits, validation, dynamic grid columns.

B. list.nth($list, $n) / nth($list, $n)

→ Get item at 1-based index (negative from end)

Use case: Access specific breakpoint, color shade, etc.

C. list.index($list, $value) / index($list, $value)

→ 1-based position or null if not found

Use case: Check existence before nth, validate variant names.

D. list.append($list, $val, $separator: auto) / append(…)

→ New list with $val added at the end

Use case: Dynamically build palettes, add modifiers.

E. list.prepend($list, $val, $separator: auto)

→ New list with $val added at the beginning

Use case: Add default/fallback first.

F. list.join($list1, $list2, $separator: auto, $bracketed: auto)

→ Merge two lists

Use case: Combine spacing scales, shadows, transitions.

G. list.remove($list, $val, $separator: auto)

→ New list without first occurrence of $val

Use case: Clean up duplicate values, remove unwanted variants.

H. list.slice($list, $start-at: 1, $end-at: -1)

→ Sub-list from start to end (negative from end)

Use case: Paginate themes, get subset of breakpoints.

I. list.zip($lists…)

→ Combine multiple lists into list of sub-lists (like zip in Python)

Use case: Pair colors with names, sizes with icons.

J. list.is-bracketed($list) / is-bracketed($list)

→ true if list uses [] brackets

Use case: Control output format for CSS grid-template-areas, etc.

K. list.separator($list) / separator($list)

→ Returns “space”, “comma”, or “slash”

Use case: Preserve separator when joining.

4. Real-World Example – Dynamic Variant Classes

→ Generates .btn–primary, .btn–secondary, etc. automatically.

5. Quick Tips & Gotchas (2026)

• Indexes are 1-based (not 0-based)
• Negative indexes count from the end (-1 = last item)
• Single values are treated as 1-item lists by most functions
• Use () for comma-separated, space for most CSS values
• For very large lists → performance can matter (rare in Sass)
• Combine with @each loops + maps for powerful systems
• Deprecations: old globals → always use module namespace now

You’ve now unlocked list superpowers! Lists + maps + loops + functions = the foundation of almost every serious Sass design system.

Next — want to build a complete spacing / typography scale using lists + math + custom functions? Or combine lists with maps for full theme objects? Or go into sass:map functions next?

Just tell me — we’re deep in the good stuff now! 🚀