Sass list.index()

Beginner
12 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass list.index finding a 1-based position in a list or returning null
Definition

Definition and Usage

list.index($list, $value) returns the 1-based index of $value in $list, or null if it is missing. Load it with @use "sass:list" on Dart Sass 1.23+. Global alias: index().

Official docs: if $value appears more than once, you get the index of its first appearance. Pair with list.nth() when you need the value at that position.

Official samples.

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

Not zero-based.

Sass list indexes start at 1 — the same convention as list.nth and list.set-nth.

Syntax

Syntax

SCSS
@use "sass:list";

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

// Global alias still works
index(1px solid red, solid);

Pattern: find a slot with index → guard against null → read or rewrite with nth / set-nth.

Reference

Index Rules

How lookups behave:

CaseResult
Value found1-based number (1 = first item)
Value missingnull
DuplicatesIndex of the first match only
Maps as listsSearches key/value pairs (two-item sublists)
Check for null before nth.

list.nth($list, null) errors. Always test $i != null (or use @if) before reading that index.

Code

SCSS Examples

Examples target Dart Sass 1.23+ with @use "sass:list". Open View Compiled CSS for verified output (matches official Sass docs samples).

Example 1 — Index Border Shorthand Parts (Official Docs)

A classic 1px solid red list has three slots.

SCSS
@use "sass:list";

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

.border {
  --width-i: #{list.index(1px solid red, 1px)};
  --style-i: #{list.index(1px solid red, solid)};
  --color-i: #{list.index(1px solid red, red)};
}

How It Works

  1. Space-separated border parts are a three-item list.
  2. 1px is at index 1.
  3. solid is at index 2; red at 3.
  4. Useful before rewriting one part with set-nth.

Example 2 — Missing Value Returns null (Official Docs)

dashed is not in the list, so the lookup is empty.

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

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

.border {
  --missing: #{meta.inspect(list.index(1px solid red, dashed))};
}

How It Works

  1. No match → official result is null.
  2. meta.inspect makes null visible in CSS output.
  3. Do not pass that result straight into nth.
  4. Treat null as “not found” in guards (Example 4).

Example 3 — Duplicates Return the First Match

When a value appears twice, only the earliest index is returned.

SCSS
@use "sass:list";

@debug list.index(red green red blue, red);  // 1
@debug list.index(red green red blue, blue); // 4

.dupes {
  --first-red: #{list.index(red green red blue, red)};
  --blue: #{list.index(red green red blue, blue)};
}

How It Works

  1. red appears twice (positions 1 and 3).
  2. First appearance wins → index 1.
  3. blue is unique at index 4.
  4. No built-in “last index” helper — scan yourself if you need it.

Example 4 — Guard, Then Read with list.nth

Safe pattern: look up, check for null, then read.

SCSS
@use "sass:list";

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

.guard {
  @if $i != null {
    --has-solid: true;
    --style: #{list.nth($border, $i)};
  } @else {
    --has-solid: false;
    --style: none;
  }
}

How It Works

  1. Find the style slot with index.
  2. @if $i != null avoids a bad nth call.
  3. list.nth returns solid at that index.
  4. Else branch would run if the token were missing.

Example 5 — Maps Count as Pair Lists

Official fun fact: maps are lists of two-item key/value pairs.

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

$theme: (primary: #036, accent: #c69);

.map-like {
  --primary-pair: #{list.index($theme, primary #036)};
  --missing-pair: #{meta.inspect(list.index($theme, accent #000))};
}

How It Works

  1. Map pairs behave like nested two-item lists.
  2. primary #036 matches the first pair → index 1.
  3. Wrong value in the pair → null.
  4. Prefer map helpers for key lookups in real themes; this shows the list view.

Edge Cases & Pitfalls

Most index bugs are zero-based thinking, forgetting null, or expecting the last duplicate match.

base

Indexes start at 1

The first item is 1, not 0 — same as nth.

null

Missing → null, not 0

Guard with @if $i != null before list.nth($list, $i).

dupes

Only the first match

Later duplicates are ignored by list.index.

eq

Values must compare equal

1px ≠ 1; quoted vs unquoted strings may not match.

Toolchain

Sass Support

Prefer the module form with Dart Sass 1.23+. Global index() remains for older call sites.

APIStatus
list.index()Dart Sass 1.23+ via @use "sass:list"
Global index()Available (prefer module form in new code)
Return typeNumber (1-based) or null
LibSass / Ruby SassNo sass:list module — use global index() if needed

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • 1-based lookup of a value in a list (or map-as-list).
  • Missing values return null — guard before nth.
  • Duplicates resolve to the first appearance only.
  • Prefer list.index after @use "sass:list".

One line: when you need a value’s position in a list, call list.index($list, $value).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:list"
2. Remember indexes are 1-based
3. Handle null when the value is missing
4. Expect the first match for duplicates
5. Pair with list.nth / list.set-nth after a successful find

Frequently Asked Questions

list.index($list, $value) returns the 1-based position of $value in $list. Example: list.index(1px solid red, solid) is 2. If the value is missing, it returns null.
1-based. The first item is index 1, not 0—the same convention as list.nth().
Official docs: the function returns null. Use != null checks before calling list.nth with that index.
list.index returns the index of the first appearance only.
Yes. Global index($list, $value) still works. New projects should prefer list.index() after @use "sass:list".
Built-in modules with @use need Dart Sass 1.23+. LibSass and Ruby Sass do not load sass:list the same way—use the global index() name there if you must.

Next: Sass list.is-bracketed()

Check whether a list uses square brackets.

list.is-bracketed() →

About the author

Mari Selvan M P
Mari Selvan M P 🔗

Developer, cloud engineer, and technical writer

  • Experience 12 years building web and cloud systems
  • Focus Full Stack Development, AWS, and Developer Education

I write practical tutorials so students and working developers can learn by doing—from databases and APIs to deployment on AWS.

AWS Certified Developer – Associate (Credly)

8 people found this page helpful

Sass list.append Function Sass list.is-bracketed Function