Sass string.index() Function

What You’ll Learn

string.index() belongs to the built-in sass:string module. It finds the first place a substring appears inside a string—using 1-based indexes—or returns null when it is missing. This page covers contains checks, pairing with string.slice, and five compiled examples.

What Is string.index()?

Official docs: returns the first index of $substring in $string, or null if $string does not contain $substring.

• Indexes start at 1 (the first character).
• Only the first match is returned.
• A missing match is null, not 0 or -1.
• Pair with string.slice to cut text around the found index.

📝 Syntax

@use "sass:string";

// Recommended
string.index($string, $substring)

// Legacy global name
str-index($string, $substring)

Parameters

Return value

📦 Loading sass:string

// Recommended — namespaced (Dart Sass 1.23+)
@use "sass:string";
$i: string.index("Helvetica Neue", "Neue"); // 11

// Optional — bring members into scope
@use "sass:string" as *;
$i: index("Helvetica Neue", "Neue");

// Legacy global
$i: str-index("Helvetica Neue", "Neue");

🎨 Official Patterns

Helvetica starts at the beginning (index 1). Count characters carefully for later matches like Neue.

⚖️ Index Number vs Contains Check

🛠 Compatibility

This is about Sass compilers, not browsers. The search runs at compile time.

Prefer current Dart Sass so the module API matches the official docs.

Examples Gallery

Each example uses string.index at compile time (Dart Sass 1.23+). Open View Compiled CSS for verified output.

@use "sass:meta";
@use "sass:string";

.probe {
  --helvetica: #{string.index("Helvetica Neue", "Helvetica")};
  --neue: #{string.index("Helvetica Neue", "Neue")};
  --miss: #{meta.inspect(string.index("Helvetica Neue", "Arial"))};
}

.probe {
  --helvetica: 1;
  --neue: 11;
  --miss: null;
}

@use "sass:string";

$class: "btn-primary";
$pos: string.index($class, "-");

.slice {
  --dash-at: #{$pos};
  --prefix: #{string.slice($class, 1, $pos - 1)};
  --suffix: #{string.slice($class, $pos + 1)};
}

.slice {
  --dash-at: 4;
  --prefix: btn;
  --suffix: primary;
}

@use "sass:string";

@function contains($haystack, $needle) {
  @return string.index($haystack, $needle) != null;
}

.check {
  --has-neue: #{contains("Helvetica Neue", "Neue")};
  --has-arial: #{contains("Helvetica Neue", "Arial")};
}

.check {
  --has-neue: true;
  --has-arial: false;
}

@use "sass:string";

@mixin if-contains($haystack, $needle) {
  @if string.index($haystack, $needle) {
    .match {
      content: "#{$needle}";
    }
  }
}

@include if-contains("card is-active", "active");
@include if-contains("card is-active", "disabled");

.match {
  content: "active";
}

@use "sass:meta";
@use "sass:string";

$paths: "icons/home.svg", "logo.png", "fonts/Roboto.woff2";

@each $path in $paths {
  $slash: string.index($path, "/");
  .file {
    --path: #{$path};
    --has-folder: #{meta.inspect($slash != null)};
    --slash-at: #{meta.inspect($slash)};
  }
}

.file {
  --path: icons/home.svg;
  --has-folder: true;
  --slash-at: 6;
}

.file {
  --path: logo.png;
  --has-folder: false;
  --slash-at: null;
}

.file {
  --path: fonts/Roboto.woff2;
  --has-folder: true;
  --slash-at: 6;
}

🚀 Real-World Use Cases

• Token parsing — find separators like - or / in names.
• Feature flags — check if a class string contains is-active.
• Path helpers — detect folders before generating asset URLs.
• Slice pipelines — locate a point, then cut with string.slice.
• Validation — require or forbid a substring before emitting CSS.

⚠️ Common Pitfalls

• 0-based habits — Sass strings start at 1, not 0.
• Expecting -1 on miss — missing matches are null.
• Interpolating null — use meta.inspect or guard with @if.
• Confusing with list.index — use the string. prefix.
• Case sensitivity — "Neue" does not match "neue".

💡 Best Practices