Sass list.append() Function

What You’ll Learn

list.append() belongs to the built-in sass:list module. It returns a copy of a list with one value added at the end. This page covers separators, nesting vs joining, module loading, Dart Sass support, and five compiled examples.

What Is list.append()?

Think of a shopping list: append means “add one more item at the bottom.” Sass does the same for space-separated or comma-separated lists while compiling your stylesheet.

• 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)

📝 Syntax

Load the list module, then call the function:

@use "sass:list";

list.append($list, $val, $separator: auto)

Parameters

Return value

📦 Loading sass:list

Modern Sass groups list helpers into the sass:list module. Prefer the namespaced form in new code.

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

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

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

🔗 Separators: Space, Comma, Slash

CSS uses different separators for different jobs: spaces in margin: 10px 20px 30px, commas in font-family: Helvetica, Arial, sans-serif. $separator controls which style the returned list uses.

📋 list.append vs list.join

Official docs: do not use list.join just to add one value—if that value is a list, join flattens it. Prefer list.append for a single add.

🛠 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 to see what Dart Sass emits (official samples where noted).

@use "sass:list";

@debug list.append(10px 20px, 30px); // 10px 20px 30px

$sizes: 10px 20px;
$sizes: list.append($sizes, 30px);

.box {
  margin: $sizes;
}

.box {
  margin: 10px 20px 30px;
}

@use "sass:list";

@debug list.append((blue, red), green); // blue, red, green

$fonts: Helvetica, Arial;
$fonts: list.append($fonts, sans-serif);

.card {
  font-family: $fonts;
}

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

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

@debug list.append(10px 20px, 30px 40px); // 10px 20px (30px 40px)

$pair: list.append(10px 20px, 30px 40px);

.demo {
  --pair: #{meta.inspect($pair)};
  padding: list.nth($pair, 1) list.nth($pair, 2);
}

.demo {
  --pair: 10px 20px (30px 40px);
  padding: 10px 20px;
}

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

@debug list.append(10px, 20px, $separator: comma); // 10px, 20px
@debug list.append((blue, red), green, $separator: space); // blue red green

.demo {
  --comma: #{meta.inspect(list.append(10px, 20px, $separator: comma))};
  --space: #{meta.inspect(list.append((blue, red), green, $separator: space))};
}

.demo {
  --comma: 10px, 20px;
  --space: blue red green;
}

@use "sass:list";

$gaps: 0.5rem;
$gaps: list.append($gaps, 1rem);
$gaps: list.append($gaps, 1.5rem);

.stack > * + * {
  margin-top: list.nth($gaps, 2); // 1rem
}

.radii {
  border-radius: list.append(4px 4px, 0);
}

.stack > * + * {
  margin-top: 1rem;
}

.radii {
  border-radius: 4px 4px 0;
}

🚀 Real-World Use Cases

• Font stacks — append a fallback family to a shared token.
• Shorthand lists — build margin, padding, or border-radius lists.
• Design scales — grow spacing or shadow stacks in loops and mixins.
• Safe single adds — prefer append over join when the new item might be a list.
• Maps as lists — Sass treats maps as lists of pairs, so list helpers can apply.

⚠️ Common Pitfalls

• Forgetting to reassign — list.append($s, 1) alone does not update $s.
• Expecting flatten — appending a list nests it; use list.join to merge elements.
• Wrong separator — font stacks need commas; shorthands usually need spaces.
• Forgetting @use — list.append is undefined until you load sass:list.
• LibSass pipelines — built-in modules need Dart Sass; use global append() carefully on legacy tooling.

💡 Best Practices