Sass list.join() Function

What You’ll Learn

list.join() belongs to the built-in sass:list module. It merges two lists into one flat list. This page covers separators, brackets, when to prefer list.append, Dart Sass support, and five compiled examples.

What Is list.join()?

Think of two stacks of tokens—spacing scales, font families, or color names. You want one list that contains every item from both. list.join builds that combined list at compile time.

• list.join(10px 20px, 30px 40px) → 10px 20px 30px 40px
• list.join((blue, red), (#abc, #def)) → blue, red, #abc, #def
• list.join(10px, 20px, $separator: comma) → 10px, 20px

📝 Syntax

Load the list module, then call the function:

@use "sass:list";

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

Parameters

Return value

📦 Loading sass:list

// Recommended — namespaced
@use "sass:list";
$all: list.join(10px 20px, 30px 40px);

// Optional — bring members into scope
@use "sass:list" as *;
$all: join(10px 20px, 30px 40px);

// Optional — custom namespace
@use "sass:list" as l;
$all: l.join(10px 20px, 30px 40px);

🔍 list.join vs list.append

This is the most important beginner trap. Both can look like “add more values,” but they treat a list-valued second argument differently.

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

// join flattens both sides into one list
$flat: list.join(10px 20px, 30px 40px);
// → 10px 20px 30px 40px

// append nests the second value as a single item
$nested: list.append(10px 20px, 30px 40px);
// → 10px 20px (30px 40px)

📋 Separators and Brackets

$separator and $bracketed are independent. You can force a comma separator, square brackets, or both.

@use "sass:list";

// Force comma separator
list.join(10px, 20px, $separator: comma); // 10px, 20px

// Inherit brackets from $list1
list.join([10px], 20px); // [10px 20px]

// Force brackets on a plain join
list.join(10px, 20px, $bracketed: true); // [10px 20px]

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS only contains the finished list values (for example in margin or font-family).

Examples Gallery

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

@use "sass:list";

@debug list.join(10px 20px, 30px 40px);              // 10px 20px 30px 40px
@debug list.join((blue, red), (#abc, #def));         // blue, red, #abc, #def

.demo {
  margin: #{list.join(10px 20px, 30px 40px)};
  --colors: #{list.join((blue, red), (#abc, #def))};
}

.demo {
  margin: 10px 20px 30px 40px;
  --colors: blue, red, #abc, #def;
}

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

@debug list.join(10px, 20px); // 10px 20px
@debug list.join(10px, 20px, $separator: comma); // 10px, 20px
@debug list.join((blue, red), (#abc, #def), $separator: space);
// blue red #abc #def

.sep {
  --a: #{meta.inspect(list.join(10px, 20px))};
  --b: #{meta.inspect(list.join(10px, 20px, $separator: comma))};
  --c: #{meta.inspect(list.join((blue, red), (#abc, #def), $separator: space))};
}

.sep {
  --a: 10px 20px;
  --b: 10px, 20px;
  --c: blue red #abc #def;
}

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

@debug list.join([10px], 20px); // [10px 20px]
@debug list.join(10px, 20px, $bracketed: true); // [10px 20px]

.br {
  --from-brack: #{meta.inspect(list.join([10px], 20px))};
  --force-on: #{meta.inspect(list.join(10px, 20px, $bracketed: true))};
  --force-off: #{meta.inspect(list.join([10px], 20px, $bracketed: false))};
}

.br {
  --from-brack: [10px 20px];
  --force-on: [10px 20px];
  --force-off: 10px 20px;
}

@use "sass:list";

$pad: 0.5rem 1rem;
$extra: 1.5rem 2rem;

$fonts-a: Helvetica, Arial;
$fonts-b: Roboto, sans-serif;

.box {
  padding: list.join($pad, $extra);
}

.card {
  font-family: list.join($fonts-a, $fonts-b);
}

.box {
  padding: 0.5rem 1rem 1.5rem 2rem;
}

.card {
  font-family: Helvetica, Arial, Roboto, sans-serif;
}

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

$nested: list.append(10px 20px, 30px 40px);
$flat: list.join(10px 20px, 30px 40px);

.compare {
  --nested: #{meta.inspect($nested)};
  --flat: #{meta.inspect($flat)};
}

.compare {
  --nested: 10px 20px (30px 40px);
  --flat: 10px 20px 30px 40px;
}

🚀 Real-World Use Cases

• Spacing / sizing scales — merge token lists into longer shorthands.
• Font stacks — combine brand fonts with system fallbacks.
• Color or name catalogs — concatenate theme lists for loops.
• Bracketed track lists — build grid-related lists with $bracketed.
• Mixin APIs — accept two partial lists and join them before emitting CSS.

⚠️ Common Pitfalls

• Using join instead of append — a list-valued “extra” gets flattened.
• Unexpected separator — auto follows $list1 first; force it when unsure.
• Forgetting brackets — only $list1 (or $bracketed) controls […].
• Forgetting @use — list.join needs sass:list.
• Mutating in place — join returns a new list; reassign if you store it.

💡 Best Practices