Sass string.insert() Function

What You’ll Learn

string.insert() belongs to the built-in sass:string module. It returns a copy of a string with new text inserted at a 1-based or negative index. This page covers out-of-range clamping, font-name building, and five compiled examples.

What Is string.insert()?

Official docs: returns a copy of $string with $insert inserted at $index. Positive indexes count from the start; negative indexes count from the end.

• The original string is not mutated—you always get a new value.
• If $index is past the end, the insert is appended.
• If $index is before the start (too negative), the insert is prepended.
• Pair with string.index when you need to find a position first.

📝 Syntax

@use "sass:string";

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

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

Parameters

Return value

📦 Loading sass:string

// Recommended — namespaced (Dart Sass 1.23+)
@use "sass:string";
$name: string.insert("Roboto Bold", " Mono", 7); // "Roboto Mono Bold"

// Optional — bring members into scope
@use "sass:string" as *;
$name: insert("Roboto Bold", " Mono", 7);

// Legacy global
$name: str-insert("Roboto Bold", " Mono", 7);

🎨 Official Patterns

Positive and negative indexes can describe the same insertion point. Huge indexes safely clamp instead of throwing.

⚖️ Positive vs Negative Indexes

🛠 Compatibility

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

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

Examples Gallery

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

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

.probe {
  --pos: #{meta.inspect(string.insert("Roboto Bold", " Mono", 7))};
  --neg: #{meta.inspect(string.insert("Roboto Bold", " Mono", -6))};
  --end: #{meta.inspect(string.insert("Roboto", " Bold", 100))};
  --start: #{meta.inspect(string.insert("Bold", "Roboto ", -100))};
}

.probe {
  --pos: "Roboto Mono Bold";
  --neg: "Roboto Mono Bold";
  --end: "Roboto Bold";
  --start: "Roboto Bold";
}

@use "sass:string";

.heading {
  font-family: string.insert("Roboto Bold", " Mono", 7), sans-serif;
}

.heading {
  font-family: "Roboto Mono Bold", sans-serif;
}

@use "sass:string";

@function with-prefix($name, $prefix) {
  @return string.insert($name, $prefix, 1);
}

.badge {
  content: with-prefix("Sale", "Mega ");
}

.badge {
  content: "Mega Sale";
}

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

$class: "btn";
$mod: "-primary";

.compare {
  --append-end: #{meta.inspect(string.insert($class, $mod, 100))};
  --insert-mid: #{meta.inspect(string.insert("iconhome", "-", 5))};
}

.compare {
  --append-end: "btn-primary";
  --insert-mid: "icon-home";
}

@use "sass:string";

$base: "card";
$parts: ("__title", "__body", "__footer");

@each $part in $parts {
  .#{string.insert($base, $part, 100)} {
    display: block;
  }
}

.card__title {
  display: block;
}

.card__body {
  display: block;
}

.card__footer {
  display: block;
}

🚀 Real-World Use Cases

• Font naming — inject weight or style words into family strings.
• BEM tooling — append __el / --mod pieces onto a block.
• Label builders — prepend badges or status text for content.
• Path helpers — insert separators after a known index from string.index.
• Safe concat — clamp indexes instead of manually checking string length.

⚠️ Common Pitfalls

• 0-based habits — Sass string indexes are 1-based.
• Forgetting spaces — include leading/trailing spaces in $insert when you need them (" Mono").
• Expecting mutation — the original variable stays unchanged.
• Wrong arg order — remember string, then insert, then index.
• Confusing with list helpers — this edits characters, not list items.

💡 Best Practices