Sass math.compatible()

Definition and Usage

math.compatible($number1, $number2) returns whether the two numbers have compatible units. If it returns true, they can safely be added, subtracted, or compared. Otherwise those operations will error. Load it with @use "sass:math" (Dart Sass 1.23+ for modules).

Syntax

@use "sass:math";

math.compatible($number1, $number2); //=> boolean

math.compatible(2px, 1px);    // true
math.compatible(100px, 3em);  // false
math.compatible(10cm, 3mm);   // true

// Global name (legacy / deprecated in modern Dart Sass)
comparable(2px, 1px); // true

// Module API — prefer math.compatible after @use "sass:math"

Pattern: inspect tokens → branch with @if → only then add or compare. Inspect units with math.unit and math.is-unitless.

When Units Match

Common pairs and their verified results:

Related Functions

Load with @use "sass:math". Previous: math.clamp(). Next: math.cos(). Also: math.unit(), math.is-unitless(), math.min(), math.max(), @if.

SCSS Examples

Examples target Dart Sass with @use "sass:math". Open View Compiled CSS for verified output (matches official Sass docs samples).

@use "sass:math";

@debug math.compatible(2px, 1px); // true

.basic {
  --a: #{math.compatible(2px, 1px)};
}

.basic {
  --a: true;
}

@use "sass:math";

@debug math.compatible(100px, 3em); // false

.fail {
  --b: #{math.compatible(100px, 3em)};
}

.fail {
  --b: false;
}

@use "sass:math";

@debug math.compatible(10cm, 3mm); // true

.convert {
  --c: #{math.compatible(10cm, 3mm)};
}

.convert {
  --c: true;
}

@use "sass:math";

.more {
  --unitless: #{math.compatible(10, 3)};
  --mixed: #{math.compatible(10, 3px)};
  --pct: #{math.compatible(10%, 3%)};
}

.more {
  --unitless: true;
  --mixed: true;
  --pct: true;
}

@use "sass:math";

$a: 12px;
$b: 1rem;

.gate {
  @if math.compatible($a, $b) {
    width: $a + $b;
  } @else {
    width: $a;
  }
}

.gate {
  width: 12px;
}

Sass Support

Prefer the module form with Dart Sass 1.23+.

Compile with the Dart Sass CLI.

Key Takeaways

Compile Notes

Practical checklist:

1. @use "sass:math"
2. Call math.compatible($a, $b)
3. true → safe to add / subtract / compare
4. false → normalize units or pick a fallback
5. Prefer math.compatible over global comparable()