Sass math.compatible() Function

What You’ll Learn

math.compatible() is a unit helper in the sass:math module. It answers one question: can these two numbers work together? This page covers the boolean return, the global comparable() alias, how it protects add/compare/clamp calls, and five compiled examples.

What Is math.compatible()?

Sass numbers often carry CSS units (px, em, cm, and so on). Some pairs can be added or compared because Sass knows how to convert them. Others cannot—and mixing them throws a compile error.

math.compatible($number1, $number2) returns whether those units are compatible. Official docs put it under Unit Functions next to helpers that inspect units.

• math.compatible(2px, 1px) → true (same unit)
• math.compatible(10cm, 3mm) → true (convertible absolute lengths)
• math.compatible(100px, 3em) → false (absolute vs relative)

📝 Syntax

Load the math module, then call the function:

@use "sass:math";

math.compatible($number1, $number2)

Parameters

Return value

📦 Loading sass:math

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

// Recommended — namespaced
@use "sass:math";
$ok: math.compatible(2px, 1px);

// Optional — bring members into the current namespace
@use "sass:math" as *;
$ok: compatible(2px, 1px);

// Optional — custom namespace
@use "sass:math" as m;
$ok: m.compatible(2px, 1px);

// Legacy global name (still works in many setups)
$ok: comparable(2px, 1px);

📏 Which Units Are Compatible?

Compatible means Sass can place the values on the same measuring stick. Same unit always works. Convertible absolute lengths (like cm and mm) work. Absolute vs relative lengths (like px and em) do not.

🛠 Compatibility

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

Examples Gallery

Each example uses @use "sass:math". Open View Compiled CSS to see what Dart Sass emits. Booleans often appear via interpolation or @if branches.

@use "sass:math";

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

.demo {
  --same-unit: #{math.compatible(2px, 1px)};
}

.demo {
  --same-unit: true;
}

@use "sass:math";

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

.checks {
  --cm-mm: #{math.compatible(10cm, 3mm)};
  --px-em: #{math.compatible(100px, 3em)};
}

.checks {
  --cm-mm: true;
  --px-em: false;
}

@use "sass:math";

$base: 12px;
$extra: 0.5in; // compatible absolute length → 48px

.safe {
  @if math.compatible($base, $extra) {
    margin-left: $base + $extra;
  } @else {
    margin-left: $base;
  }
}

$bad: 2em;

.unsafe-fallback {
  @if math.compatible($base, $bad) {
    margin-left: $base + $bad;
  } @else {
    margin-left: $base; // px + em would error
  }
}

.safe {
  margin-left: 60px;
}

.unsafe-fallback {
  margin-left: 12px;
}

@use "sass:math";

@mixin offset($from, $by) {
  @if math.compatible($from, $by) {
    transform: translateX($from + $by);
  } @else {
    transform: translateX($from);
  }
}

.card {
  @include offset(24px, 1cm); // 1cm ≈ 37.795px → ~61.795px
}

.chip {
  @include offset(24px, 1rem); // incompatible → keep 24px
}

.card {
  transform: translateX(61.7952755906px);
}

.chip {
  transform: translateX(24px);
}

@use "sass:math";

.names {
  --module: #{math.compatible(10cm, 3mm)};
  --global: #{comparable(10cm, 3mm)};
}

.names {
  --module: true;
  --global: true;
}

🚀 Real-World Use Cases

• Theme maps — validate user tokens before adding gaps or paddings.
• Shared mixins — accept any length-like args and fail soft when units clash.
• Design systems — assert that spacing scales stay in one unit family.
• Pre-checks for clamp/min/max — avoid cryptic unit errors deeper in a stack.
• Migration tooling — flag files that still mix px with em/rem.
• Learning units — print true/false custom properties while exploring Sass units.

⚠️ Common Pitfalls

• Expecting conversion — compatible only returns a boolean; it does not rewrite units for you.
• Mixing px and em/rem — almost always false; normalize the family first.
• Percent with lengths — 10% and 20px are not compatible.
• Putting the boolean in CSS blindly — prefer @if for real styles; use custom properties mainly for debugging.
• Confusing the two names — module = compatible, global = comparable.

💡 Best Practices