Sass math.is-unitless() Function

What You’ll Learn

math.is-unitless() is a unit helper in the sass:math module. It answers one question: does this number have any CSS units? This page covers the boolean return, the global unitless() alias, how it guards exponential and inverse-trig helpers, and five compiled examples.

What Is math.is-unitless()?

A Sass number is either unitless (just a magnitude like 100) or it carries a CSS unit (100px, 50%, 45deg). Some math helpers only accept unitless input. Others behave differently when units are present.

math.is-unitless($number) returns whether the value has no units. Official docs place it under Unit Functions next to math.compatible().

• math.is-unitless(100) → true
• math.is-unitless(100px) → false
• math.is-unitless(math.div(24px, 16px)) → true (units cancel)

📝 Syntax

Load the math module, then call the function:

@use "sass:math";

math.is-unitless($number)

Parameters

Return value

📦 Loading sass:math

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

// Recommended — namespaced
@use "sass:math";
$ok: math.is-unitless(100);

// Optional — bring members into the current namespace
@use "sass:math" as *;
$ok: is-unitless(100);

// Optional — custom namespace
@use "sass:math" as m;
$ok: m.is-unitless(100);

// Legacy global name (still works in many setups)
$ok: unitless(100);

📏 What Counts as Unitless?

Any attached unit makes the answer false—including percentages, angles, times, and compound units like px*px. Dividing matching units away (for example px / px) produces a unitless ratio.

🛠 Compatibility

This is about Sass compilers, not browsers. The boolean is resolved while compiling—browsers never see a math.is-unitless() call.

Examples Gallery

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

@use "sass:math";

@debug math.is-unitless(100);   // true
@debug math.is-unitless(100px); // false

.demo {
  --plain: #{math.is-unitless(100)};
  --length: #{math.is-unitless(100px)};
}

.demo {
  --plain: true;
  --length: false;
}

@use "sass:math";

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

.scale {
  --is-unitless: #{math.is-unitless($ratio)};

  @if math.is-unitless($ratio) {
    opacity: $ratio;
  }
}

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

@use "sass:math";

$n: 18px;

.panel {
  @if math.is-unitless($n) {
    --curve: #{math.log($n)};
  } @else {
    // Strip px so log can run
    --curve: #{math.log(math.div($n, 1px))};
  }
}

.panel {
  --curve: 2.8903717579;
}

@use "sass:math";

@mixin fade($value, $base: 100px) {
  @if math.is-unitless($value) {
    opacity: $value;
  } @else if math.compatible($value, $base) {
    opacity: math.div($value, $base);
  } @else {
    opacity: 1;
  }
}

.a { @include fade(0.4); }
.b { @include fade(40px); }
.c { @include fade(2em); } // incompatible with 100px → fallback

.a {
  opacity: 0.4;
}

.b {
  opacity: 0.4;
}

.c {
  opacity: 1;
}

@use "sass:math";

.names {
  --module: #{math.is-unitless(100)};
  --global: #{unitless(100)};
  --with-unit: #{math.is-unitless(12rem)};
}

.names {
  --module: true;
  --global: true;
  --with-unit: false;
}

🚀 Real-World Use Cases

• Before log / pow / sqrt — those helpers reject lengths; check or strip first.
• Opacity and scales — confirm a token is a ratio, not a length.
• Flexible mixins — accept either 0.5 or 50px / 100px style inputs.
• Design-token validation — assert that multiplier maps stay unitless.
• Inverse trig inputs — guard acos/asin/atan ratios.
• Learning units — print true/false while exploring how division cancels units.

⚠️ Common Pitfalls

• Thinking zero is special — 0px is still not unitless.
• Expecting stripping — the function only reports; use math.div to remove a known unit.
• Percentages — % counts as a unit, so is-unitless(50%) is false.
• Confusing the two names — module = is-unitless, global = unitless.
• Skipping the check before log/pow — those calls error on lengths at compile time.

💡 Best Practices