string.split($string, $separator, $limit: null) returns a bracketed, comma-separated list of substrings of $string split on $separator. Separators are not included. Load with @use "sass:string".
string.split("Segoe UI Emoji", " ") becomes ["Segoe", "UI", "Emoji"].
With $limit: 1 or higher, Sass splits on at most that many separators; the last item keeps the remainder.
string.split needs Dart Sass 1.57+—newer than most other sass:string helpers (1.23+).
@use "sass:string";
string.split($string, $separator, $limit: null) //=> list
string.split("Segoe UI Emoji", " ");
// ["Segoe", "UI", "Emoji"]
string.split("Segoe UI Emoji", " ", $limit: 1);
// ["Segoe", "UI Emoji"]
// No legacy global name — module API only
// Prefer @use "sass:string" (Dart Sass 1.57+)Pattern: pick a separator → get a list of parts → walk with @each or list.nth.
How $limit changes the result:
| Limit | Behavior |
|---|---|
null (default) | Split on every separator |
1 or higher | Split on at most that many separators |
| Max items | At most $limit + 1 substrings |
| Last item | Keeps the rest of the string, including leftover separators |
Examples use @use "sass:string". Open View Compiled CSS for verified Dart Sass output (matches official Sass docs samples where shown).
Full split vs a single-separator limit.
@use "sass:meta";
@use "sass:string";
.probe {
--all: #{meta.inspect(string.split("Segoe UI Emoji", " "))};
--limit: #{meta.inspect(string.split("Segoe UI Emoji", " ", $limit: 1))};
}"UI Emoji".Split on "--" fully, then once with a limit.
@use "sass:meta";
@use "sass:string";
$full: string.split("a--b--c", "--");
$once: string.split("a--b--c", "--", $limit: 1);
.compare {
--full: #{meta.inspect($full)};
--once: #{meta.inspect($once)};
}--.b--c intact.list.nthSplit a class-like string, then read one item and the count.
@use "sass:list";
@use "sass:meta";
@use "sass:string";
$parts: string.split("btn primary large", " ");
$mod: list.nth($parts, 2);
.btn {
--mod: #{meta.inspect($mod)};
--count: #{list.length($parts)};
}@eachEmit a custom property for each split token.
@use "sass:meta";
@use "sass:string";
$parts: string.split("Segoe UI Emoji", " ");
.loop {
@each $part in $parts {
--p-#{$part}: #{meta.inspect($part)};
}
}Turn a space-separated token string into utility rules.
@use "sass:string";
$tokens: string.split("primary accent muted", " ");
@each $token in $tokens {
.chip-#{$token} {
content: $token;
}
}Most split bugs are wrong limits or treating the result like a string.
Use list.nth, list.length, or @each—not string helpers on the whole result.
$limit: 1 means one split → up to two parts; leftover separators stay in the last item.
meta.inspect shows ["a", "b"]—that bracketed form is intentional.
Older toolchains may miss string.split even if other sass:string helpers work.
Module-only API on current Dart Sass.
| API | Status |
|---|---|
string.split() | Dart Sass 1.57+ via @use "sass:string" |
| Return type | Bracketed, comma-separated list |
| Separators | Not included in the substrings |
| Legacy global | None — no str-split() |
Compile with the Dart Sass CLI.
nth, length, @each.One line: to turn a string into a list of parts, use string.split($string, $separator).
Practical checklist:
1. @use "sass:string" (Dart Sass 1.57+)
2. Pass $string and $separator
3. Expect a bracketed comma-separated list
4. Use $limit when you need a head / remainder split
5. Walk results with @each or list.nth / list.lengthConvert ASCII letters in a string to lower case.
8 people found this page helpful