list.nth($list, $n) returns the element of $list at index $n. Indexes are 1-based. If $n is negative, it counts from the end (-1 is last). Load it with @use "sass:list" on Dart Sass 1.23+. Global alias: nth().
Official docs: Sass throws if there is no element at $n. Guard with list.length(), or only call nth after list.index() returns a non-null index.
list.nth(10px 12px 16px, 2) → 12px. list.nth([line1, line2, line3], -1) → line3.
@use "sass:list";
list.nth(10px 12px 16px, 2); // 12px
list.nth(10px 12px 16px, 1); // 10px
list.nth(10px 12px 16px, -1); // 16px
list.nth([line1, line2, line3], -1); // line3
// Global alias still works
nth(10px 12px 16px, 2);Pattern: find a slot with index (or loop 1…length) → read with nth → rewrite with set-nth when needed.
How $n is interpreted:
| Index | Meaning |
|---|---|
1 | First item |
2, 3, … | Later items from the start |
-1 | Last item |
-2 | Second-to-last item |
Out of range / null | Compile error — guard first |
index answers “where is this value?” nth answers “what is at this position?” Use them together for safe lookups.
Examples target Dart Sass 1.23+ with @use "sass:list". Open View Compiled CSS for verified output (matches official Sass docs samples).
Index 2 on a three-item spacing list.
@use "sass:list";
@debug list.nth(10px 12px 16px, 2); // 12px
.space {
--mid: #{list.nth(10px 12px 16px, 2)};
--first: #{list.nth(10px 12px 16px, 1)};
}10px.12px.-1 is the last item; -2 is second-to-last.
@use "sass:list";
@debug list.nth([line1, line2, line3], -1); // line3
.bracketed {
--last: #{list.nth([line1, line2, line3], -1)};
}
.space {
--second-last: #{list.nth(10px 12px 16px, -2)};
}-1 picks the last bracketed item line3.-2 on 10px 12px 16px is 12px.Read width, style, and color by fixed positions.
@use "sass:list";
$border: 1px solid red;
.border {
--width: #{list.nth($border, 1)};
--style: #{list.nth($border, 2)};
--color: #{list.nth($border, 3)};
}1…length with nthSafe iteration pattern for spacing scales.
@use "sass:list";
$sizes: 8px 16px 24px 32px;
.loop {
@for $i from 1 through list.length($sizes) {
--s#{$i}: #{list.nth($sizes, $i)};
}
}list.length sets the loop upper bound.@for from 1 matches 1-based indexes.nth reads one spacing step.index, Then Read with nthNull-safe lookup when you know the value but not the slot.
@use "sass:list";
$border: 1px solid red;
$i: list.index($border, solid);
.with-index {
@if $i != null {
--style: #{list.nth($border, $i)};
}
}index finds the style slot (or returns null).@if $i != null blocks a bad nth call.nth returns solid at that index.Most nth bugs are zero-based thinking, passing null from index, or reading past list.length.
There is no index 0. First item is always 1.
Compare against list.length before hard-coded indexes.
list.nth($list, null) errors. Guard after list.index.
-5 on a 3-item list is still out of range.
Prefer the module form with Dart Sass 1.23+. Global nth() remains for older call sites.
| API | Status |
|---|---|
list.nth() | Dart Sass 1.23+ via @use "sass:list" |
Global 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 nth() if needed |
Compile with the Dart Sass CLI.
-1 = last).@use "sass:list".One line: when you need the value at a position, call list.nth($list, $n).
Practical checklist:
1. @use "sass:list"
2. Remember indexes are 1-based
3. Use -1 for the last item
4. Never pass a null index into nth
5. Loop with @for $i from 1 through list.length($list)Replace the value at a 1-based (or negative) index.
8 people found this page helpful