list.set-nth($list, $n, $value) returns a copy of $list with the element at index $n replaced by $value. Indexes are 1-based. Negative $n counts from the end (-1 is last). Load it with @use "sass:list" on Dart Sass 1.23+. Global alias: set-nth().
Official docs: Sass throws if there is no existing element at $n. Guard with list.length(), or only set after list.index() returns a non-null index.
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.
@use "sass:list";
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
// Global alias still works
set-nth(10px 20px 30px, 2, 1rem);Pattern: find a slot with index or pick a fixed position → rewrite with set-nth → reassign if you need to keep growing the same variable.
How replacement works:
| Idea | Meaning |
|---|---|
$n: 1 | Replace the first item |
$n: -1 | Replace the last item |
| Immutability | Returns a new list; original is unchanged |
vs list.nth | nth reads; set-nth writes a copy |
Out of range / null | Compile error — guard first |
Space lists stay space-separated; comma lists stay comma-separated after the replacement.
Examples target Dart Sass 1.23+ with @use "sass:list". Open View Compiled CSS for verified output (matches official Sass docs samples).
Swap the leading spacing token for 2em.
@use "sass:list";
@debug list.set-nth(10px 20px 30px, 1, 2em); // 2em 20px 30px
.box {
margin: list.set-nth(10px 20px 30px, 1, 2em);
}10px becomes 2em; the rest stay.-1 (Official Docs)Negative indexes count from the end.
@use "sass:list";
@debug list.set-nth(10px 20px 30px, -1, 8em); // 10px 20px 8em
.last {
--sizes: #{list.set-nth(10px 20px 30px, -1, 8em)};
}-1 means the last item.30px becomes 8em.Replace the third comma-separated family.
@use "sass:list";
@debug list.set-nth((Helvetica, Arial, sans-serif), 3, Roboto);
// Helvetica, Arial, Roboto
.fonts {
font-family: list.set-nth((Helvetica, Arial, sans-serif), 3, Roboto);
}sans-serif with Roboto.index, Then ReplaceChange border style without hard-coding the slot.
@use "sass:list";
$border: 1px solid red;
$i: list.index($border, solid);
.border {
@if $i != null {
border: list.set-nth($border, $i, dashed);
}
}index finds the style slot.@if $i != null blocks a bad set-nth call.dashed in place of solid.Each call returns a new list — reassign to keep changes.
@use "sass:list";
$sizes: 8px 16px 24px 32px;
$sizes: list.set-nth($sizes, 2, 18px);
$sizes: list.set-nth($sizes, -1, 40px);
.chain {
padding: $sizes;
}2 to 18px.40px.Most set-nth bugs are forgetting to reassign, passing a null index, or writing past list.length.
Write $list: list.set-nth($list, $n, $val); — the helper does not mutate in place.
Compare against list.length before hard-coded indexes.
Guard after list.index with @if $i != null.
Same convention as list.nth — there is no index 0.
Prefer the module form with Dart Sass 1.23+. Global set-nth() remains for older call sites.
| API | Status |
|---|---|
list.set-nth() | Dart Sass 1.23+ via @use "sass:list" |
Global set-nth() | Available (prefer module form in new code) |
| Indexes | 1-based; negatives count from the end |
| LibSass / Ruby Sass | No sass:list module — use global set-nth() if needed |
Compile with the Dart Sass CLI.
-1 = last).@use "sass:list".One line: when you need to replace the value at a position, call list.set-nth($list, $n, $value).
Practical checklist:
1. @use "sass:list"
2. Remember indexes are 1-based
3. Use -1 to replace the last item
4. Reassign: $list: list.set-nth($list, $n, $val)
5. Guard null indexes from list.index before set-nthBuild a slash-separated list for CSS values like font-size/line-height.
8 people found this page helpful