Sass list.set-nth() Function

What You’ll Learn

list.set-nth() belongs to the built-in sass:list module. It returns a copy of a list with one slot replaced. This page covers 1-based indexes, negatives from the end, immutability, pairing with list.nth, Dart Sass support, and five compiled examples.

What Is list.set-nth()?

When you need to swap one token in a spacing scale, change a border style, or update the last font in a stack, list.set-nth builds a new list with that slot changed—without rewriting the whole list by hand.

• list.set-nth(10px 20px 30px, 1, 2em) → 2em 20px 30px
• list.set-nth(10px 20px 30px, -1, 8em) → 10px 20px 8em
• list.set-nth((Helvetica, Arial, sans-serif), 3, Roboto) → Helvetica, Arial, Roboto

📝 Syntax

Load the list module, then call the function:

@use "sass:list";

list.set-nth($list, $n, $value)

Parameters

Return value

📦 Loading sass:list

// Recommended — namespaced
@use "sass:list";
$next: list.set-nth(10px 20px 30px, 1, 2em);

// Optional — bring members into scope
@use "sass:list" as *;
$next: set-nth(10px 20px 30px, 1, 2em);

// Optional — custom namespace
@use "sass:list" as l;
$next: l.set-nth(10px 20px 30px, 1, 2em);

🔍 Immutable Copies

Sass lists are not mutated in place. Always capture the return value—or the original list stays unchanged.

@use "sass:list";

$orig: 10px 20px 30px;

// Wrong expectation: $orig is still 10px 20px 30px
list.set-nth($orig, 2, 99px);

// Correct: keep the new list
$copy: list.set-nth($orig, 2, 99px);
// or update the same name:
// $orig: list.set-nth($orig, 2, 99px);

📋 list.set-nth vs list.nth

🛠 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.set-nth(10px 20px 30px, 1, 2em); // 2em 20px 30px
@debug list.set-nth(10px 20px 30px, -1, 8em); // 10px 20px 8em
@debug list.set-nth((Helvetica, Arial, sans-serif), 3, Roboto);
// Helvetica, Arial, Roboto

.demo {
  --a: #{meta.inspect(list.set-nth(10px 20px 30px, 1, 2em))};
  --b: #{meta.inspect(list.set-nth(10px 20px 30px, -1, 8em))};
  --c: #{meta.inspect(list.set-nth((Helvetica, Arial, sans-serif), 3, Roboto))};
}

.demo {
  --a: 2em 20px 30px;
  --b: 10px 20px 8em;
  --c: Helvetica, Arial, Roboto;
}

@use "sass:list";

$border: 1px solid #336699;
$border-dashed: list.set-nth($border, 2, dashed);
$border-wide: list.set-nth($border, 1, 3px);

.box {
  border: $border-dashed;
}

.wide {
  border: $border-wide;
}

.box {
  border: 1px dashed #336699;
}

.wide {
  border: 3px solid #336699;
}

@use "sass:list";

$gaps: 0.25rem 0.5rem 1rem 1.5rem 2rem;
$gaps-lg: list.set-nth($gaps, -1, 3rem);
$gaps-sm: list.set-nth($gaps, 1, 0.125rem);

.scale {
  --orig-last: #{list.nth($gaps, -1)};
  --new-last: #{list.nth($gaps-lg, -1)};
  --new-first: #{list.nth($gaps-sm, 1)};
  padding: $gaps-lg;
}

.scale {
  --orig-last: 2rem;
  --new-last: 3rem;
  --new-first: 0.125rem;
  padding: 0.25rem 0.5rem 1rem 1.5rem 3rem;
}

@use "sass:list";

$fonts: Helvetica, Arial, sans-serif;
$fonts-roboto: list.set-nth($fonts, 3, Roboto);

.card {
  font-family: $fonts-roboto;
}

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

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

$orig: 10px 20px 30px;
$copy: list.set-nth($orig, 2, 99px);

.compare {
  --orig: #{meta.inspect($orig)};
  --copy: #{meta.inspect($copy)};
}

.compare {
  --orig: 10px 20px 30px;
  --copy: 10px 99px 30px;
}

🚀 Real-World Use Cases

• Theme variants — tweak one slot of a shared spacing or size scale.
• Border / shorthand tokens — swap width, style, or color independently.
• Font stacks — replace a family without rewriting the whole comma list.
• Mixin APIs — accept a base list and return a customized copy.
• Safe updates — combine with list.index when the slot is found by value.

⚠️ Common Pitfalls

• Forgetting to reassign — calling set-nth alone does not update the variable.
• 0-based thinking — the first item is 1, not 0.
• Out-of-range indexes — Sass errors if the slot does not exist.
• Confusing with nth — nth reads; set-nth returns a modified copy.
• Forgetting @use — list.set-nth needs sass:list.

💡 Best Practices