Sass string.split() Function

What You’ll Learn

string.split() belongs to the built-in sass:string module. It turns one string into a list of pieces using a separator. This page covers the optional $limit, pairing with sass:list, and five compiled examples.

What Is string.split()?

Official docs: returns a bracketed, comma-separated list of substrings of $string that are separated by $separator. The separators are not included in those substrings.

• You get a list, not a single string—use list.nth or @each.
• Optional $limit stops after a fixed number of splits.
• When limited, the last piece keeps whatever is left (including leftover separators).
• Requires Dart Sass 1.57+ (newer than most other sass:string helpers).

📝 Syntax

@use "sass:string";

// Module API only (Dart Sass 1.57+)
string.split($string, $separator, $limit: null)

Parameters

Return value

📦 Loading sass:string

// Recommended — namespaced (Dart Sass 1.57+)
@use "sass:string";
$parts: string.split("Segoe UI Emoji", " "); // ["Segoe", "UI", "Emoji"]

// Optional — bring members into scope
@use "sass:string" as *;
$parts: split("Segoe UI Emoji", " ");

🎨 Official Patterns

With $limit: 1, Sass cuts once. The second item keeps the remaining space and text.

⚖️ Understanding $limit

🛠 Compatibility

This is about Sass compilers, not browsers. Splitting happens at compile time.

Prefer current Dart Sass 1.57+. Other string helpers often need only 1.23+; split is newer.

Examples Gallery

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

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

.probe {
  --all: #{meta.inspect(string.split("Segoe UI Emoji", " "))};
  --limited: #{meta.inspect(string.split("Segoe UI Emoji", " ", $limit: 1))};
}

.probe {
  --all: ["Segoe", "UI", "Emoji"];
  --limited: ["Segoe", "UI Emoji"];
}

@use "sass:list";
@use "sass:string";

$parts: string.split("Segoe UI Emoji", " ");

.font {
  font-family: list.nth($parts, 1), list.nth($parts, 2), list.nth($parts, 3), sans-serif;
}

.font {
  font-family: "Segoe", "UI", "Emoji", sans-serif;
}

@use "sass:list";
@use "sass:string";

$path: "themes/dark/card";
$segments: string.split($path, "/");

.card {
  --depth: #{list.length($segments)};
  --leaf: #{list.nth($segments, -1)};
}

.card {
  --depth: 3;
  --leaf: card;
}

@use "sass:list";
@use "sass:string";

$class: "btn--primary--lg";
$parts: string.split($class, "--", $limit: 1);

.mod {
  --block: #{list.nth($parts, 1)};
  --rest: #{list.nth($parts, 2)};
}

.mod {
  --block: btn;
  --rest: primary--lg;
}

@use "sass:string";

$csv: "red,green,blue";
$colors: string.split($csv, ",");

@each $color in $colors {
  .swatch-#{$color} {
    background: #{$color};
  }
}

.swatch-red {
  background: red;
}

.swatch-green {
  background: green;
}

.swatch-blue {
  background: blue;
}

🚀 Real-World Use Cases

• Font stacks — break a family string into individual names.
• Path tooling — read folders and leaf names from / segments.
• BEM helpers — cut once on -- to separate block vs modifiers.
• Token loops — turn CSV-like strings into @each generators.
• Config strings — parse simple space- or comma-delimited options at compile time.

⚠️ Common Pitfalls

• Expecting a string — the return value is a list.
• Forgetting leftover separators — with $limit, the last item may still contain separators.
• Old compilers — needs Dart Sass 1.57+; LibSass/Ruby Sass cannot run it.
• Looking for str-split — there is no official legacy global name.
• Confusing with string.slice — slice returns one substring; split returns many pieces.

💡 Best Practices