Sass string.insert()

Beginner
8 min read
Updated: Nov 2026
5 examples
Dart Sass 1.23+
Sass string.insert inserting text into a string at a 1-based or negative index
Definition

Definition and Usage

string.insert($string, $insert, $index) returns a copy of $string with $insert placed at $index. Indexes are 1-based (or negative from the end). Load with @use "sass:string".

Official sample idea.

insert("Roboto Bold", " Mono", 7) and insert(…, -6) both become "Roboto Mono Bold".

Out-of-range clamps.

Too-large positive indexes append. Too-small negative indexes prepend.

Original stays unchanged.

You always get a new string. Pair with string.index() when you need to find where to insert.

Syntax

Syntax

SCSS
@use "sass:string";

string.insert($string, $insert, $index) //=> string

string.insert("Roboto Bold", " Mono", 7); // "Roboto Mono Bold"
string.insert("Roboto Bold", " Mono", -6); // "Roboto Mono Bold"
string.insert("Roboto", " Bold", 100); // "Roboto Bold" (append)
string.insert("Bold", "Roboto ", -100); // "Roboto Bold" (prepend)

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

Pattern: choose where to splice → get a new string → use it in CSS or as a class name.

Reference

Indexes & Clamping

How $index is read:

IndexBehavior
Positive (e.g. 7)Count from the start; 1 is before the first character
Negative (e.g. -6)Count from the end
Larger than lengthAppend to the end
Smaller than negative lengthPrepend to the beginning
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 Insert Samples

Positive index, negative index, and both clamp cases.

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

How It Works

  1. Positive 7 inserts before character 7.
  2. Negative -6 can land on the same spot.
  3. 100 clamps to the end.
  4. -100 clamps to the start.

Example 2 — Build a Font Family Name

Insert a weight word into a family string for CSS.

SCSS
@use "sass:string";

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

How It Works

  1. insert builds the family name.
  2. Quotes stay in the CSS output.
  3. sans-serif remains the fallback.
  4. Matches the official Roboto sample idea.

Example 3 — Prefix Helper

Insert at index 1 to put text at the front.

SCSS
@use "sass:string";

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

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

How It Works

  1. Index 1 inserts before the first character.
  2. Prefix lands at the front.
  3. @function packages the pattern.
  4. Clean prepend without manual concatenation.

Example 4 — Append and Mid Insert

Clamp to the end, or splice a separator in the middle.

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

How It Works

  1. Large index appends without measuring length.
  2. Mid insert splices - between parts.
  3. inspect keeps quotes visible in custom props.
  4. Useful for class and token building.

Example 5 — BEM Element Loop

Append element suffixes onto a block name.

SCSS
@use "sass:string";

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

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

How It Works

  1. Huge index appends each __* suffix.
  2. #{…} drops Sass quotes in the selector.
  3. @each builds several class names.
  4. Same clamp pattern as the official end sample.

Edge Cases & Pitfalls

Most insert bugs are 0-based thinking or forgetting it returns a copy.

1-based

Index 1 is the start

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

clamp

Out-of-range is intentional

Huge positives append; very negative values prepend.

copy

Original is not mutated

Capture the return value; the input string stays the same.

find

Need a dynamic spot?

Find it first with string.index.

Toolchain

Sass Support

Prefer the module form with current Dart Sass.

APIStatus
string.insert()Dart Sass 1.23+ via @use "sass:string"
Return typeString (copy)
Indexes1-based and negative; out-of-range clamps
Legacy globalstr-insert($string, $insert, $index)

Compile with the Dart Sass CLI.

Remember

Key Takeaways

  • Inserts a copy of text at a 1-based or negative index.
  • Out-of-range clamps to prepend or append.
  • Pairs with index when the insert point is dynamic.
  • Prefer @use "sass:string" (Dart Sass 1.23+).

One line: to splice text into a string, use string.insert($string, $insert, $index).

Practice

Compile Notes

Practical checklist:

checklist.txt
1. @use "sass:string"
2. Pass $string, $insert, $index
3. Remember indexes are 1-based / negative
4. Capture the returned copy
5. Use a huge index to append, or index 1 to prepend

Frequently Asked Questions

string.insert($string, $insert, $index) returns a copy of $string with $insert inserted at $index. Example: string.insert("Roboto Bold", " Mono", 7) becomes "Roboto Mono Bold".
Positive indexes count from the start (1 is the first character). Negative indexes count from the end. Official sample: string.insert("Roboto Bold", " Mono", -6) also yields "Roboto Mono Bold".
If $index is higher than the string length, $insert is added to the end. If $index is smaller than the negative length, $insert is added to the beginning.
No. It returns a new string. The original value is unchanged.
Yes. str-insert($string, $insert, $index) is the legacy global name. Prefer string.insert 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.length()

Count how many characters are in a string.

string.length() →

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 string.index Function Sass string.length Function