Sass list.index() Function

What You’ll Learn

list.index() belongs to the built-in sass:list module. It finds where a value sits in a list (or returns null). This page covers 1-based indexes, missing values, duplicates, pairing with list.nth, Dart Sass support, and five compiled examples.

What Is list.index()?

Imagine a space-separated CSS value like 1px solid red. You may need to ask: “Which slot holds solid?” list.index answers with a number at compile time.

• list.index(1px solid red, 1px) → 1
• list.index(1px solid red, solid) → 2
• list.index(1px solid red, dashed) → null

📝 Syntax

Load the list module, then call the function:

@use "sass:list";

list.index($list, $value)

Parameters

Return value

📦 Loading sass:list

// Recommended — namespaced
@use "sass:list";
$i: list.index(1px solid red, solid);

// Optional — bring members into scope
@use "sass:list" as *;
$i: index(1px solid red, solid);

// Optional — custom namespace
@use "sass:list" as l;
$i: l.index(1px solid red, solid);

🔍 Handling null

Missing values return null. Always guard before you pass the result into list.nth, which errors on a bad index.

@use "sass:list";

$gaps: 0.5rem 1rem 1.5rem;
$i: list.index($gaps, 1rem);

$space: if($i != null, list.nth($gaps, $i), 0);

📋 list.index 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.index(1px solid red, 1px);    // 1
@debug list.index(1px solid red, solid);  // 2

.box {
  --width-at: #{list.index(1px solid red, 1px)};
  --style-at: #{list.index(1px solid red, solid)};
}

.box {
  --width-at: 1;
  --style-at: 2;
}

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

@debug list.index(1px solid red, dashed); // null

$gaps: 0.5rem 1rem 1.5rem;
$hit: list.index($gaps, 2rem);
$mid: list.index($gaps, 1rem);

.demo {
  --hit: #{meta.inspect($hit)};
  --mid: #{$mid};
  margin-top: if($mid != null, list.nth($gaps, $mid), 0);
}

.demo {
  --hit: null;
  --mid: 2;
  margin-top: 1rem;
}

@use "sass:list";

$border: 1px solid #336699;
$i: list.index($border, solid);

.box {
  --solid-at: #{$i};
  border-style: if($i != null, list.nth($border, $i), none);
}

.box {
  --solid-at: 2;
  border-style: solid;
}

@use "sass:list";

$fonts: Helvetica, Arial, sans-serif;
$pos: list.index($fonts, Arial);

.card {
  --arial: #{$pos};
}

.card {
  --arial: 2;
}

@use "sass:list";

$dup: 10px 20px 10px;

.dup {
  --first: #{list.index($dup, 10px)};
}

.dup {
  --first: 1;
}

🚀 Real-World Use Cases

• Border / background lists — find width, style, or color slots.
• Design scales — check whether a spacing token exists before using it.
• Font stacks — locate a family before swapping with list.set-nth.
• Feature flags in lists — test membership via != null.
• Mixin guards — skip logic when a required keyword is absent.

⚠️ Common Pitfalls

• 0-based thinking — the first item is 1, not 0.
• Using null with nth — always check $i != null first.
• Assuming last duplicate — only the first match is returned.
• Forgetting @use — list.index needs sass:list.
• Type mismatches — 1 and 1px are different Sass values.

💡 Best Practices