Sass string.index()

Beginner
8 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass string.index finding the first 1-based position of a substring
Definition

Definition and Usage

string.index($string, $substring) returns the first 1-based index of $substring in $string, or null if it is not found. Load with @use "sass:string".

Official sample idea.

string.index("Helvetica Neue", "Helvetica") → 1; index(…, "Neue") → 11.

1-based indexes.

The first character is at index 1, not 0—same convention as other Sass string helpers.

Missing = null.

Guard with @if or compare to null before using the result with string.slice().

Syntax

Syntax

SCSS
@use "sass:string";

string.index($string, $substring) //=> number | null

string.index("Helvetica Neue", "Helvetica"); // 1
string.index("Helvetica Neue", "Neue"); // 11
string.index("Helvetica Neue", "Arial"); // null

// Contains check:
string.index($haystack, $needle) != null

// Safe branch:
@if string.index($haystack, $needle) { ... }

// Global alias (legacy): str-index($string, $substring)
// Prefer string.index after @use "sass:string"

Pattern: search for a substring → get a 1-based index or null → branch or feed into slice.

Reference

Index Notes

Quick facts for everyday use:

SituationResult
Substring at the start1
Substring later in the stringFirst matching index
Substring missingnull
Contains checkindex(...) != null
Code

SCSS Examples

Examples use @use "sass:string". Open View Compiled CSS for verified Dart Sass output (matches official Sass docs samples where shown).

Example 1 — Official Index Samples

Find positions, and inspect null when missing.

SCSS
@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"))};
}

How It Works

  1. Helvetica starts at index 1.
  2. Neue starts at index 11.
  3. Arial is missing → null.
  4. meta.inspect prints null safely into CSS.

Example 2 — Split on a Dash with slice

Find -, then cut prefix and suffix.

SCSS
@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)};
}

How It Works

  1. index finds the dash at 4.
  2. slice left takes characters before the dash.
  3. slice right takes characters after it.
  4. Pair with slice for simple token splits.

Example 3 — Contains Helper

Turn index into a clear boolean.

SCSS
@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")};
}

How It Works

  1. Any number means the substring was found.
  2. null means it was missing.
  3. != null turns that into a boolean.
  4. Reusable for mixin and function guards.

Example 4 — Guard with @if

Only emit CSS when the substring exists.

SCSS
@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");

How It Works

  1. First include finds active.
  2. Second include returns null.
  3. @if skips the missing case.
  4. Useful for optional design-system flags.

Example 5 — Detect Folders in Paths

Check whether a path string contains /.

SCSS
@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)};
  }
}

How It Works

  1. @each scans every path.
  2. / present → report the index.
  3. Flat filenames return null.
  4. Same helper works for any delimiter search.

Edge Cases & Pitfalls

Most index bugs are 0-based thinking or forgetting null.

1-based

First character is 1

Do not treat Sass string indexes like JavaScript’s 0-based indexes.

null

Missing returns null

Guard before math or slice, or compare with != null.

first

Only the first match

Repeated substrings still return the earliest index.

inspect

Print null with meta.inspect

Use meta.inspect when dumping null into CSS custom properties.

Toolchain

Sass Support

Prefer the module form with current Dart Sass.

APIStatus
string.index()Dart Sass 1.23+ via @use "sass:string"
Return typeNumber (1-based) or null
Legacy globalstr-index($string, $substring)

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Returns a 1-based index of the first substring match.
  • Missing = null — guard before using the number.
  • Pairs with slice for prefix/suffix splits.
  • Prefer @use "sass:string" (Dart Sass 1.23+).

One line: to find where a substring starts, use string.index($string, $substring).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:string"
2. Pass $string and $substring
3. Expect a 1-based index or null
4. Guard before math / slice
5. Use != null for contains checks

Frequently Asked Questions

string.index($string, $substring) returns the first index of $substring in $string, or null if it is not found. Example: string.index("Helvetica Neue", "Helvetica") is 1.
Sass string indexes are 1-based. The first character is at index 1, not 0.
The function returns null when $string does not contain $substring.
Compare the result to null: string.index($haystack, $needle) != null. Or use @if string.index(...) { ... }.
Yes. str-index($string, $substring) is the legacy global name. Prefer string.index after @use "sass:string".
Dart Sass 1.23+. LibSass and Ruby Sass do not load sass:string with @use; they may still offer the legacy global name.

Next: Sass string.insert()

Insert text into a string at a 1-based index.

string.insert() →

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 selector.unify Function Sass string.insert Function