list.append($list, $val, $separator: auto) returns a copy of $list with $val added at the end. Load it with @use "sass:list" on Dart Sass 1.23+. Global alias: append().
Official note: unlike list.join(), if $val is itself a list it is nested inside the result rather than flattened.
list.append(10px 20px, 30px) → 10px 20px 30px. list.append((blue, red), green) → blue, red, green. list.append(10px 20px, 30px 40px) → 10px 20px (30px 40px).
Single values count as one-item lists, and maps count as lists of key/value pairs — so append works on those shapes too.
@use "sass:list";
list.append(10px 20px, 30px); // 10px 20px 30px
list.append((blue, red), green); // blue, red, green
list.append(10px 20px, 30px 40px); // 10px 20px (30px 40px)
list.append(10px, 20px, $separator: comma); // 10px, 20px
list.append((blue, red), green, $separator: space); // blue red green
// Global alias still works
append(10px 20px, 30px);Pattern: grow spacing / color tokens with append → use join only when you want to flatten two lists together.
How the arguments behave:
| Argument / idea | Meaning |
|---|---|
$separator: auto | Keep $list’s separator (or space if it has none) |
comma / space / slash | Force that separator on the returned list |
| Nesting | If $val is a list, it becomes one nested item |
vs list.join | join flattens two lists; prefer append for one value |
Official docs: if that value is a list, join concatenates it. Use list.append() when you mean “add one item.”
Examples target Dart Sass 1.23+ with @use "sass:list". Open View Compiled CSS for verified output (matches official Sass docs samples).
Add a third spacing token onto 10px 20px.
@use "sass:list";
@debug list.append(10px 20px, 30px); // 10px 20px 30px
.box {
margin: list.append(10px 20px, 30px);
}auto separator keeps spaces.Grow a color list while keeping commas.
@use "sass:list";
@debug list.append((blue, red), green); // blue, red, green
.palette {
--colors: #{list.append((blue, red), green)};
}green is appended as the third item.auto.join (Official Docs)Appending a list nests it. Use meta.inspect / length to see the structure (CSS alone flattens).
@use "sass:list";
@use "sass:meta";
@debug list.append(10px 20px, 30px 40px); // 10px 20px (30px 40px)
$nested: list.append(10px 20px, 30px 40px);
.report {
--length: #{list.length($nested)};
--inspect: #{meta.inspect($nested)};
--join: #{meta.inspect(list.join(10px 20px, 30px 40px))};
}join flattens to four items instead.append; two lists → join.$separator (Official Docs)Override the returned list’s separator explicitly.
@use "sass:list";
@debug list.append(10px, 20px, $separator: comma); // 10px, 20px
@debug list.append((blue, red), green, $separator: space); // blue red green
.forced {
--pair: #{list.append(10px, 20px, $separator: comma)};
--colors: #{list.append((blue, red), green, $separator: space)};
}auto.$separator: comma forces commas.$separator: space can rewrite a comma list into spaces.slash (see list.slash()).Reassign as you append — lists are immutable copies.
@use "sass:list";
$base: 8px 16px;
$grow: list.append($base, 24px);
$grow: list.append($grow, 32px);
.stack {
padding: $grow;
}$grow to keep extending it.Most append bugs are expecting join-style flattening, forgetting to reassign, or misunderstanding $separator.
list.append(10px 20px, 30px 40px) has length 3. Use join when you want four flat items.
Write $sizes: list.append($sizes, 30px); — calling append alone does not update $sizes.
Only auto, comma, space, and slash are allowed.
Inspect with meta.inspect / list.length when teaching nested structure.
Prefer the module form with Dart Sass 1.23+. Global append() remains for older call sites.
| API | Status |
|---|---|
list.append() | Dart Sass 1.23+ via @use "sass:list" |
Global append() | Available (prefer module form in new code) |
$separator | auto, comma, space, slash |
| LibSass / Ruby Sass | No sass:list module — use global append() if needed |
Compile with the Dart Sass CLI.
join only when you want to flatten.One line: when you need one more item on a list, call list.append($list, $val).
Practical checklist:
1. @use "sass:list"
2. Prefer list.append for a single new item
3. Use list.join only to flatten two lists
4. Pass $separator when you need comma / space / slash
5. Reassign: $list: list.append($list, $val)Find the 1-based index of a value in a list.
8 people found this page helpful