Sass math.unit() Function

What You’ll Learn

math.unit() is a unit helper in the sass:math module. It turns a number’s units into a quoted string you can @debug, compare while learning, or print into CSS for inspection. This page covers empty strings, compound units, the global unit() alias, the official debugging caveat, and five compiled examples.

What Is math.unit()?

Every Sass number has a magnitude and optional units. math.unit($number) returns a quoted string that describes those units. Official docs place it under Unit Functions next to math.is-unitless() and math.compatible().

• math.unit(100) → "" (unitless)
• math.unit(100px) → "px"
• math.unit(5px * 10px) → "px*px"
• math.unit(math.div(5px, 1s)) → "px/s"

📝 Syntax

Load the math module, then call the function:

@use "sass:math";

math.unit($number)

Parameters

Return value

📦 Loading sass:math

Prefer the module API. Official docs also document a global name, unit(), for older stylesheets.

// Recommended — namespaced
@use "sass:math";
$u: math.unit(100px);

// Optional — bring members into the current namespace
@use "sass:math" as *;
$u: unit(100px); // math module member

// Optional — custom namespace
@use "sass:math" as m;
$u: m.unit(100px);

// Legacy global name (still works in many setups)
$u: unit(100px);

📏 What the String Looks Like

Simple units print as themselves. Multiplying lengths builds compound units with *. Dividing units builds a numerator/denominator form with /. Canceling matching units (for example px / px) leaves an empty string.

🛠 Compatibility

This is about Sass compilers, not browsers. The string is produced while compiling—browsers never see a math.unit() call unless you interpolate the result into CSS on purpose.

Examples Gallery

Each example uses @use "sass:math". Open View Compiled CSS to see what Dart Sass emits.

@use "sass:math";

@debug math.unit(100);   // ""
@debug math.unit(100px); // "px"

.demo {
  --empty: "#{math.unit(100)}";
  --px: #{math.unit(100px)};
}

.demo {
  --empty: "";
  --px: px;
}

@use "sass:math";

@debug math.unit(5px * 10px);          // "px*px"
@debug math.unit(math.div(5px, 1s)); // "px/s"

.physics {
  --area: #{math.unit(5px * 10px)};
  --speed: #{math.unit(math.div(5px, 1s))};
}

.physics {
  --area: px*px;
  --speed: px/s;
}

@use "sass:math";

$ratio: math.div(24px, 16px); // 1.5

.scale {
  --units: "#{math.unit($ratio)}";
  --is-unitless: #{math.is-unitless($ratio)};
  opacity: $ratio;
}

.scale {
  --units: "";
  --is-unitless: true;
  opacity: 1.5;
}

@use "sass:math";

@mixin show-unit($value) {
  &::after {
    content: math.unit($value);
  }
}

.box {
  width: 18px;
  @include show-unit(18px);
}

.chip {
  @include show-unit(10%);
}

.box {
  width: 18px;
}
.box::after {
  content: "px";
}

.chip::after {
  content: "%";
}

@use "sass:math";

.names {
  --module: #{math.unit(100px)};
  --global: #{unit(1deg)};
  --empty: "#{math.unit(42)}";
}

.names {
  --module: px;
  --global: deg;
  --empty: "";
}

🚀 Real-World Use Cases

• @debug while learning — print units for confusing intermediate values.
• Compound math tracing — spot unexpected px*px or px/s results.
• Teaching units — show how division cancels units into "".
• Temporary DevTools labels — write unit strings into custom properties while exploring.
• Pairing with is-unitless — confirm both the boolean and the string during refactors.
• Migration audits — quickly see which tokens still carry em, rem, or %.

⚠️ Common Pitfalls

• Treating the string as a stable API — docs warn the format may change across versions.
• Expecting a boolean — use math.is-unitless() for yes/no checks.
• Empty string surprises — unitless values return "", not "none" or null.
• Interpolating without quotes — empty units can disappear visually; wrap with "#{...}" when debugging.
• Building production branches on exact matches — prefer compatible / is-unitless for real logic.

💡 Best Practices