Sass string.to-upper-case() Function

What You’ll Learn

string.to-upper-case() belongs to the built-in sass:string module. It returns a copy of a string with ASCII letters converted to upper case. This page covers quote state, Sass vs CSS text-transform, and five compiled examples.

What Is string.to-upper-case()?

Official docs: returns a copy of $string with the ASCII letters converted to upper case.

• The original string is not mutated—you always get a new value.
• Quoted strings stay quoted; unquoted strings stay unquoted.
• Hyphens, digits, and spaces are left alone.
• Pair with string.to-lower-case when you need the opposite.

📝 Syntax

@use "sass:string";

// Recommended
string.to-upper-case($string)

// Legacy global name
to-upper-case($string)

Parameters

Return value

📦 Loading sass:string

// Recommended — namespaced (Dart Sass 1.23+)
@use "sass:string";
$label: string.to-upper-case("Bold"); // "BOLD"

// Optional — bring members into scope
@use "sass:string" as *;
$label: to-upper-case("Bold");

// Legacy global
$label: to-upper-case("Bold");

🎨 Official Patterns

These are the official Sass documentation samples. Notice the hyphen stays, and quote state matches the input.

⚖️ Sass vs CSS text-transform

🛠 Compatibility

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

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

Examples Gallery

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

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

.probe {
  --quoted: #{meta.inspect(string.to-upper-case("Bold"))};
  --unquoted: #{meta.inspect(string.to-upper-case(sans-serif))};
}

.probe {
  --quoted: "BOLD";
  --unquoted: SANS-SERIF;
}

@use "sass:string";

.heading {
  font-family: string.to-upper-case("roboto"), sans-serif;
  text-transform: none;
}

.heading {
  font-family: "ROBOTO", sans-serif;
  text-transform: none;
}

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

$mod: "primary";

.btn {
  --mod: #{meta.inspect(string.to-upper-case($mod))};
}

.btn {
  --mod: "PRIMARY";
}

@use "sass:string";

@function upper-id($name) {
  @return string.to-upper-case($name);
}

.badge::before {
  content: upper-id("new");
}

.badge::before {
  content: "NEW";
}

@use "sass:string";

$parts: ("save", "edit", "delete");

@each $part in $parts {
  .action-#{string.to-upper-case($part)} {
    content: string.to-upper-case($part);
  }
}

.action-SAVE {
  content: "SAVE";
}

.action-EDIT {
  content: "EDIT";
}

.action-DELETE {
  content: "DELETE";
}

🚀 Real-World Use Cases

• Token normalization — force modifiers or flags into a fixed case.
• Generated class names — uppercase segments in BEM-style or utility loops.
• Pseudo-element labels — bake uppercase into content strings.
• Debug props — print uppercase variants with meta.inspect.
• Pair with lower-case — normalize both directions in shared helpers.

⚠️ Common Pitfalls

• Expecting Unicode casing — docs convert ASCII letters; use CSS for display casing of rich text.
• Confusing with text-transform — Sass changes the value; CSS changes display.
• Expecting mutation — the original variable stays unchanged.
• Forgetting quote state — quoted inputs stay quoted in the result.
• Uppercasing for looks only — prefer CSS when you only want visual uppercase.

💡 Best Practices