list.length($list) returns how many items are in $list. Load it with @use "sass:list" on Dart Sass 1.23+. Global alias: length().
Official docs: a single value counts as a one-item list (length 1), and a map returns the number of key/value pairs. Pair with list.nth() when looping by index.
list.length(10px) → 1. list.length(10px 20px 30px) → 3. list.length((width: 10px, height: 20px)) → 2.
list.append(10px 20px, 30px 40px) has length 3, not 4. Use list.join() when you want a flat count.
@use "sass:list";
list.length(10px); // 1
list.length(10px 20px 30px); // 3
list.length((width: 10px, height: 20px)); // 2
list.length(()); // 0
list.length([]); // 0
// Global alias still works
length(10px 20px 30px);Pattern: read length → guard or loop 1…length with nth.
How different shapes are counted:
| Input | Length |
|---|---|
Single value 10px | 1 |
| Space / comma list of n items | n |
| Map with n pairs | n (pairs, not keys alone) |
() or [] | 0 |
Nested item from append | Counts as one top-level item |
list.length([a, b, c]) is still 3. Bracketedness is a separate flag — see list.is-bracketed().
Examples target Dart Sass 1.23+ with @use "sass:list". Open View Compiled CSS for verified output (matches official Sass docs samples).
1 (Official Docs)Individual values count as one-item lists.
@use "sass:list";
@debug list.length(10px); // 1
.single {
--len: #{list.length(10px)};
}10px is treated as a one-item list.1, not an error.join(10px, 20px).Three spacing tokens → length 3.
@use "sass:list";
@debug list.length(10px 20px 30px); // 3
.space {
--len: #{list.length(10px 20px 30px)};
}1…n loop with nth.Official fun fact: maps count as lists of key/value pairs.
@use "sass:list";
@debug list.length((width: 10px, height: 20px)); // 2
.map-like {
--len: #{list.length((width: 10px, height: 20px))};
}2.Length ignores whether brackets are present.
@use "sass:list";
.shapes {
--empty-parens: #{list.length(())};
--empty-brackets: #{list.length([])};
--comma: #{list.length((blue, red, green))};
--bracketed: #{list.length([1fr 2fr 1fr])};
}() and [] — both have length 0.3.append vs joinSame inputs, different structure — length makes it obvious.
@use "sass:list";
$sizes: 8px 16px 24px 32px;
.compare {
--append-len: #{list.length(list.append(10px 20px, 30px 40px))};
--join-len: #{list.length(list.join(10px 20px, 30px 40px))};
}
.guard {
@if list.length($sizes) >= 3 {
--ok: true;
--count: #{list.length($sizes)};
} @else {
--ok: false;
}
}3.4.Most length bugs are expecting nested items to count separately, or confusing brackets with item count.
append nesting keeps a shorter length than a flattened join.
Do not special-case lone values unless you need to — they are valid lists.
list.length($map) is pair count, not a deep walk of nested maps.
Guard before nth when length might be zero.
Prefer the module form with Dart Sass 1.23+. Global length() remains for older call sites.
| API | Status |
|---|---|
list.length() | Dart Sass 1.23+ via @use "sass:list" |
Global length() | Available (prefer module form in new code) |
| Return type | Number (≥ 0) |
| LibSass / Ruby Sass | No sass:list module — use global length() if needed |
Compile with the Dart Sass CLI.
0.@use "sass:list".One line: when you need how many items a list has, call list.length($list).
Practical checklist:
1. @use "sass:list"
2. Remember singles have length 1
3. Maps return pair counts
4. Use length to spot append nesting vs join flattening
5. Guard empty lists before nth / set-nthRead whether a list uses space, comma, or slash.
8 people found this page helpful