list.join($list1, $list2, $separator: auto, $bracketed: auto) returns a new list with every element of $list1 followed by every element of $list2 — flattened into one list. Load it with @use "sass:list" on Dart Sass 1.23+. Global alias: join().
Official docs: because single values count as one-item lists, join can add a value — but if that value is a list it will be concatenated. Use list.append() to add one item; use join to combine two lists.
list.join(10px 20px, 30px 40px) → 10px 20px 30px 40px. list.join((blue, red), (#abc, #def)) → blue, red, #abc, #def. list.join(10px, 20px, $bracketed: true) → [10px 20px].
@use "sass:list";
list.join(10px 20px, 30px 40px); // 10px 20px 30px 40px
list.join((blue, red), (#abc, #def)); // blue, red, #abc, #def
list.join(10px, 20px); // 10px 20px
list.join(10px, 20px, $separator: comma); // 10px, 20px
list.join((blue, red), (#abc, #def), $separator: space); // blue red #abc #def
list.join([10px], 20px); // [10px 20px]
list.join(10px, 20px, $bracketed: true); // [10px 20px]
// Global alias still works
join(10px 20px, 30px 40px);Pattern: flatten two token lists with join → use append when you mean “one more item.”
How the optional arguments behave:
| Argument | Meaning |
|---|---|
$separator: auto | Use $list1’s separator if any, else $list2’s, else space |
comma / space / slash | Force that separator on the result |
$bracketed: auto | Keep brackets if $list1 is bracketed |
$bracketed: true / falsey | Force […], or strip brackets |
vs list.append | join flattens; append nests a list value |
Use list.is-bracketed() to confirm the result shape after $bracketed: true.
Examples target Dart Sass 1.23+ with @use "sass:list". Open View Compiled CSS for verified output (matches official Sass docs samples).
Merge spacing tokens into one four-item list.
@use "sass:list";
@debug list.join(10px 20px, 30px 40px); // 10px 20px 30px 40px
.box {
margin: list.join(10px 20px, 30px 40px);
}auto keeps the space separator.Comma lists stay comma-separated under auto.
@use "sass:list";
@debug list.join((blue, red), (#abc, #def)); // blue, red, #abc, #def
.palette {
--colors: #{list.join((blue, red), (#abc, #def))};
}$list1.$separator (Official Docs)Override the result separator explicitly.
@use "sass:list";
@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
.forced {
--space: #{list.join(10px, 20px)};
--comma: #{list.join(10px, 20px, $separator: comma)};
--colors: #{list.join((blue, red), (#abc, #def), $separator: space)};
}auto.$separator: comma forces commas.$separator: space rewrites comma inputs into spaces.slash (see list.slash()).Bracketed $list1 keeps brackets; or force them with $bracketed: true.
@use "sass:list";
@use "sass:meta";
@debug list.join([10px], 20px); // [10px 20px]
@debug list.join(10px, 20px, $bracketed: true); // [10px 20px]
.brackets {
--from-list: #{meta.inspect(list.join([10px], 20px))};
--forced: #{meta.inspect(list.join(10px, 20px, $bracketed: true))};
--check: #{list.is-bracketed(list.join(10px, 20px, $bracketed: true))};
}$bracketed: auto copies brackets from $list1.$bracketed: true forces square brackets on plain inputs.meta.inspect keeps the […] visible.is-bracketed confirms the forced result.join Flattens, append NestsSame inputs, different structure — pick the helper that matches intent.
@use "sass:list";
@use "sass:meta";
.compare {
--join: #{meta.inspect(list.join(10px 20px, 30px 40px))};
--append: #{meta.inspect(list.append(10px 20px, 30px 40px))};
--join-len: #{list.length(list.join(10px 20px, 30px 40px))};
--append-len: #{list.length(list.append(10px 20px, 30px 40px))};
}4 vs 3).join; one value → append.Most join bugs are using it like append, misunderstanding auto separator/brackets, or forgetting singles are lists.
If that value is a list, join flattens it. Prefer list.append.
Then $list2, then space. Force comma / space / slash when you need certainty.
Only the first list’s brackets are inherited. Pass true to force […].
list.join(10px, 20px) is valid — both sides are lists of length 1.
Prefer the module form with Dart Sass 1.23+. Global join() remains for older call sites.
| API | Status |
|---|---|
list.join() | Dart Sass 1.23+ via @use "sass:list" |
Global join() | Available (prefer module form in new code) |
$separator | auto, comma, space, slash |
| LibSass / Ruby Sass | No sass:list module — use global join() if needed |
Compile with the Dart Sass CLI.
@use "sass:list".One line: when you need one flat list from two lists, call list.join($list1, $list2).
Practical checklist:
1. @use "sass:list"
2. Use join to flatten two lists
3. Use append to add one value
4. Pass $separator when auto is ambiguous
5. Pass $bracketed: true when CSS needs […]Count how many items (or map pairs) a list has.
8 people found this page helpful