Sass list.separator() Function

What You’ll Learn

list.separator() belongs to the built-in sass:list module. It reports how list items are separated. This page covers space, comma, and slash, defaults for singles and empty lists, pairing with list.join / list.slash, Dart Sass support, and five compiled examples.

What Is list.separator()?

Sass lists can be space-separated (1px solid red), comma-separated ((Helvetica, Arial), or slash-separated (1px / 50px / 100px). list.separator returns which kind you have—as an unquoted string name.

• list.separator(1px 2px 3px) → space
• list.separator((1px, 2px, 3px)) → comma
• list.separator("Helvetica") → space (no separator → space)
• list.separator(()) → space

📝 Syntax

Load the list module, then call the function:

@use "sass:list";

list.separator($list)

Parameters

Return value

📦 Loading sass:list

// Recommended — namespaced
@use "sass:list";
$sep: list.separator(1px 2px 3px);

// Optional — bring members into scope
@use "sass:list" as *;
$sep: separator(1px 2px 3px);

// Optional — custom namespace
@use "sass:list" as l;
$sep: l.separator(1px 2px 3px);

// Legacy global (no @use module API)
// $sep: list-separator(1px 2px 3px);

🔍 Slash Separators with list.slash

Slash-separated lists are common for ratios and some CSS shorthands. Build them with list.slash, then inspect with list.separator.

@use "sass:list";

$tracks: list.slash(1px, 50px, 100px);
// → 1px / 50px / 100px

list.separator($tracks); // slash

📋 list.separator vs list.is-bracketed

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS only contains the finished list values you choose to emit.

Examples Gallery

Each example uses @use "sass:list". Open View Compiled CSS for verified Dart Sass output (official samples where noted).

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

@debug list.separator(1px 2px 3px);       // space
@debug list.separator((1px, 2px, 3px));   // comma
@debug list.separator("Helvetica");       // space
@debug list.separator(());                // space

$slash: list.slash(1px, 50px, 100px);

.sep {
  --space: #{meta.inspect(list.separator(1px 2px 3px))};
  --comma: #{meta.inspect(list.separator((1px, 2px, 3px)))};
  --single: #{meta.inspect(list.separator("Helvetica"))};
  --empty: #{meta.inspect(list.separator(()))};
  --slash: #{meta.inspect(list.separator($slash))};
}

.sep {
  --space: space;
  --comma: comma;
  --single: space;
  --empty: space;
  --slash: slash;
}

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

$joined-space: list.join(10px 20px, 30px, $separator: space);
$joined-comma: list.join(10px, 20px, $separator: comma);
$brack: [a, b, c];

.join {
  --js: #{meta.inspect(list.separator($joined-space))};
  --jc: #{meta.inspect(list.separator($joined-comma))};
  --br: #{meta.inspect(list.separator($brack))};
}

.join {
  --js: space;
  --jc: comma;
  --br: comma;
}

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

@mixin echo-sep($name, $list) {
  .#{$name} {
    --sep: #{meta.inspect(list.separator($list))};
    content: "#{meta.inspect($list)}";
  }
}

@include echo-sep("plain", 1rem 2rem);
@include echo-sep("fonts", (Helvetica, Arial, sans-serif));
@include echo-sep("ratio", list.slash(16, 9));

.plain {
  --sep: space;
  content: "1rem 2rem";
}

.fonts {
  --sep: comma;
  content: "Helvetica, Arial, sans-serif";
}

.ratio {
  --sep: slash;
  content: "16 / 9";
}

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

$border: 1px solid #336699;

.box {
  --sep: #{meta.inspect(list.separator($border))};
  border: $border;
}

.box {
  --sep: space;
  border: 1px solid #336699;
}

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

$ratio: list.slash(16, 9);

.hero {
  --sep: #{meta.inspect(list.separator($ratio))};
  aspect-ratio: $ratio;
}

.hero {
  --sep: slash;
  aspect-ratio: 16 / 9;
}

🚀 Real-World Use Cases

• Mixin APIs — branch when a caller passes comma vs space lists.
• Debugging joins — verify $separator after list.join.
• Font stacks — confirm comma separation before emitting font-family.
• Ratios / tracks — assert slash lists from list.slash.
• Border / margin tokens — document that design tokens are space lists.

⚠️ Common Pitfalls

• Calling global separator() — the legacy name is list-separator().
• Expecting null for singles — singles and empty lists return space.
• Mixing up brackets — use list.is-bracketed for […].
• Comma args in mixins — wrap comma lists in parentheses when passing arguments.
• Forgetting @use — list.separator needs sass:list.

💡 Best Practices