Sass Lists

What You’ll Learn

Sass lists hold a sequence of values. This page covers separators, brackets, 1-based indexes, nth / append / index, @each, immutability, argument lists, and five compiled examples.

What Are Sass Lists?

Official docs: lists contain a sequence of other values. Elements can be separated by commas (Helvetica, Arial, sans-serif), spaces (10px 15px 0 0), or slashes—as long as the separator is consistent within the list.

Unlike many languages, Sass lists do not require brackets. Any expressions separated with spaces or commas count as a list. Square brackets ([line1 line2]) are allowed and especially useful for values like grid-template-columns.

• Use parentheses to nest lists or disambiguate separators.
• Single values act like one-element lists for most list functions.
• Empty unbracketed () is not valid CSS in a property value.
• Indexes start at 1; -1 is the last item.

📝 Syntax

$space: 10px 12px 16px;                 // space-separated
$comma: Helvetica, Arial, sans-serif;   // comma-separated
$lines: [line1, line2, line3];          // bracketed
$nested: (1, 2), (3, 4);                // list of lists

➗ Slash-Separated Lists

Official docs: slash-separated lists represent values like font: 12px/30px or modern color alpha syntax. Because / historically meant division, you cannot reliably write slash lists as literals today. Create them with list.slash() while stylesheets migrate to math.div().

@use "sass:list";

$font-shorthand: list.slash(12px, 30px); // 12px / 30px

🧮 Using Lists

Load @use "sass:list" for helpers. Common ones:

Loop with @each: @each $item in $list { … }.

🔒 Immutability

Official docs: Sass lists never change in place. list.append and friends return new lists. That avoids sneaky bugs when the same list is shared. To grow a collection, reassign: $prefixes: list.append($prefixes, $next);

📦 Argument Lists

When a mixin or function takes arbitrary arguments with $args..., you get a special argument list. It behaves like a normal list of positional values, and keyword arguments are available as a map via meta.keywords($args).

Examples Gallery

Each example shows a common list pattern. Open View Compiled CSS for verified output.

@use "sass:list";
@use "sass:meta";

$fonts: Helvetica, Arial, sans-serif;
$space: 10px 12px 16px;
$lines: [line1, line2, line3];

.lists {
  --nth: #{meta.inspect(list.nth($space, 2))};
  --last: #{meta.inspect(list.nth($lines, -1))};
  --len: #{meta.inspect(list.length($space))};
  --sep-space: #{meta.inspect(list.separator($space))};
  --sep-comma: #{meta.inspect(list.separator($fonts))};
  --bracketed: #{meta.inspect(list.is-bracketed($lines))};
}

.lists {
  --nth: 12px;
  --last: line3;
  --len: 3;
  --sep-space: space;
  --sep-comma: comma;
  --bracketed: true;
}

$sizes: 40px, 50px, 80px;

@each $size in $sizes {
  .icon-#{$size} {
    font-size: $size;
    height: $size;
    width: $size;
  }
}

.icon-40px {
  font-size: 40px;
  height: 40px;
  width: 40px;
}

.icon-50px {
  font-size: 50px;
  height: 50px;
  width: 50px;
}

.icon-80px {
  font-size: 80px;
  height: 80px;
  width: 80px;
}

@use "sass:list";
@use "sass:meta";

$base: 10px 12px 16px;
$with-extra: list.append($base, 25px);
$grid: list.append([col1-line1], col1-line2);

.append-demo {
  --base: #{meta.inspect($base)};
  --extra: #{meta.inspect($with-extra)};
  --grid: #{meta.inspect($grid)};
}

.append-demo {
  --base: 10px 12px 16px;
  --extra: 10px 12px 16px 25px;
  --grid: [col1-line1 col1-line2];
}

@use "sass:list";
@use "sass:meta";

$valid-sides: top, bottom, left, right;

@mixin attach($side) {
  @if not list.index($valid-sides, $side) {
    @error "#{$side} is not a valid side. Expected one of #{$valid-sides}.";
  }

  border-#{$side}: 2px solid currentColor;
}

.box {
  @include attach(left);
}

.check {
  --i1: #{meta.inspect(list.index(1px solid red, 1px))};
  --i2: #{meta.inspect(list.index(1px solid red, solid))};
  --missing: #{meta.inspect(list.index(1px solid red, dashed))};
}

.box {
  border-left: 2px solid currentColor;
}

.check {
  --i1: 1;
  --i2: 2;
  --missing: null;
}

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

$prefixes-by-browser: ("firefox": moz, "safari": webkit, "ie": ms);

@function prefixes-for-browsers($browsers) {
  $prefixes: ();
  @each $browser in $browsers {
    $prefixes: list.append($prefixes, map.get($prefixes-by-browser, $browser));
  }
  @return $prefixes;
}

@mixin syntax-colors($args...) {
  @each $name, $color in meta.keywords($args) {
    pre span.stx-#{$name} {
      color: $color;
    }
  }
}

.demo {
  --pfx: #{meta.inspect(prefixes-for-browsers("firefox" "ie"))};
  --slash: #{meta.inspect(list.slash(12px, 30px))};
}

@include syntax-colors(
  $string: #080,
  $comment: #800,
  $variable: #60b,
);

.demo {
  --pfx: moz ms;
  --slash: 12px / 30px;
}

pre span.stx-string {
  color: #080;
}

pre span.stx-comment {
  color: #800;
}

pre span.stx-variable {
  color: #60b;
}

🚀 Real-World Use Cases

• Utility generators — sizes, spacings, or breakpoints in one list.
• Font stacks — comma-separated family lists.
• Grid tracks — bracketed line-name lists.
• Validation — allow-lists checked with list.index.
• Flexible mixins — $args... plus meta.keywords.

⚠️ Common Pitfalls

• 0-based indexes — Sass lists start at 1.
• Expecting mutation — append does not change the original list.
• Empty () in CSS — unbracketed empty lists are invalid property values.
• Comma lists as arguments — wrap with extra parentheses when passing one list to a function.
• Writing slash lists literally — use list.slash() instead of relying on /.

💡 Best Practices