Sass list.length() Function

What You’ll Learn

list.length() belongs to the built-in sass:list module. It counts how many items a list holds. This page covers single values, empty lists, maps as lists of pairs, looping with @for and list.nth, Dart Sass support, and five compiled examples.

What Is list.length()?

Before you loop a spacing scale or check whether a font stack has enough fallbacks, you need a count. list.length returns that number at compile time.

• list.length(10px) → 1
• list.length(10px 20px 30px) → 3
• list.length((width: 10px, height: 20px)) → 2

📝 Syntax

Load the list module, then call the function:

@use "sass:list";

list.length($list)

Parameters

Return value

📦 Loading sass:list

// Recommended — namespaced
@use "sass:list";
$n: list.length(10px 20px 30px);

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

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

🔍 Length of Maps

Official docs note that every map counts as a list of two-element pairs. So list.length on a map returns the number of entries—handy before you loop keys or validate a theme object.

@use "sass:list";
@use "sass:map";

$theme: (
  primary: #336699,
  accent: #e67e22,
  muted: #94a3b8,
);

$pairs: list.length($theme);      // 3
$keys: list.length(map.keys($theme)); // also 3

📋 list.length vs list.nth

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS only contains the finished numbers or property 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";

@debug list.length(10px); // 1
@debug list.length(10px 20px 30px); // 3
@debug list.length((width: 10px, height: 20px)); // 2

.count {
  --a: #{list.length(10px)};
  --b: #{list.length(10px 20px 30px)};
  --c: #{list.length((width: 10px, height: 20px))};
}

.count {
  --a: 1;
  --b: 3;
  --c: 2;
}

@use "sass:list";

$gaps: 0.25rem 0.5rem 1rem 1.5rem 2rem;
$empty: ();
$brack: [a, b, c];

.shapes {
  --gaps: #{list.length($gaps)};
  --empty: #{list.length($empty)};
  --brack: #{list.length($brack)};
}

.shapes {
  --gaps: 5;
  --empty: 0;
  --brack: 3;
}

@use "sass:list";
@use "sass:map";

$theme: (
  primary: #336699,
  accent: #e67e22,
  muted: #94a3b8,
);

.theme {
  --map-len: #{list.length($theme)};
  --map-keys: #{list.length(map.keys($theme))};
}

.theme {
  --map-len: 3;
  --map-keys: 3;
}

@use "sass:list";

$gaps: 0.25rem 0.5rem 1rem 1.5rem 2rem;

@for $i from 1 through list.length($gaps) {
  .gap-#{$i} {
    margin-top: list.nth($gaps, $i);
  }
}

.gap-1 {
  margin-top: 0.25rem;
}

.gap-2 {
  margin-top: 0.5rem;
}

.gap-3 {
  margin-top: 1rem;
}

.gap-4 {
  margin-top: 1.5rem;
}

.gap-5 {
  margin-top: 2rem;
}

@use "sass:list";

$fonts: Helvetica, Arial, sans-serif;

.card {
  --font-count: #{list.length($fonts)};
  font-family: $fonts;
}

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

🚀 Real-World Use Cases

• Utility generators — drive @for loops over spacing or size scales.
• Theme validation — assert a map has the expected number of tokens.
• Mixin guards — skip logic when a list is empty (length == 0).
• Font / shadow stacks — document or debug how many items you emit.
• Safe indexing — compare an index against length before calling list.nth.

⚠️ Common Pitfalls

• 0-based loops — Sass list indexes start at 1, so use from 1 through length.
• Nested lists — a nested sublist counts as one item unless you flatten first.
• Expecting CSS length() — this is Sass compile-time, not the CSS length() idea.
• Forgetting @use — list.length needs sass:list.
• Confusing maps with lists of values — map length is pair count, not flattened values.

💡 Best Practices