Sass math.percentage() Function

What You’ll Learn

math.percentage() turns a unitless decimal into a CSS % value in the sass:math module. This page covers the unitless rule, the fun fact that it equals $number * 100%, pairing with math.div(), the global percentage() alias, and five compiled examples.

What Is math.percentage()?

Design tokens often store fractions like 0.2 or ratios from math.div. CSS widths, columns, and progress bars usually want 20% instead. math.percentage($number) multiplies that unitless value by 100% for you.

Official docs place it under Other Functions and call out a fun fact: it is identical to writing $number * 100%.

• math.percentage(0.2) → 20%
• math.percentage(math.div(100px, 50px)) → 200%
• math.percentage(1) → 100%

📝 Syntax

Load the math module, then call the function:

@use "sass:math";

math.percentage($number)

Parameters

Return value

📦 Loading sass:math

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

// Recommended — namespaced
@use "sass:math";
$w: math.percentage(0.2);

// Optional — bring members into the current namespace
@use "sass:math" as *;
$w: percentage(0.2);

// Optional — custom namespace
@use "sass:math" as m;
$w: m.percentage(0.2);

// Legacy global name (still works in many setups)
$w: percentage(0.2);

📏 Unitless Input Only

The argument must have no units. Lengths like 20px fail. Cancel units first with math.div(), then convert.

🛠 Compatibility

This is about Sass compilers, not browsers. Compiled CSS receives a finished percentage—no math.percentage() call remains.

Examples Gallery

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

@use "sass:math";

@debug math.percentage(0.2); // 20%

.panel {
  width: math.percentage(0.2);
}

.panel {
  width: 20%;
}

@use "sass:math";

@debug math.percentage(math.div(100px, 50px)); // 200%

.hero {
  flex-basis: math.percentage(math.div(100px, 50px));
}

.hero {
  flex-basis: 200%;
}

@use "sass:math";

$fraction: 0.35;

.box {
  width: math.percentage($fraction);
  max-width: $fraction * 100%;
}

.box {
  width: 35%;
  max-width: 35%;
}

@use "sass:math";

$cols: 12;
$span-main: 8;
$span-side: 4;

.main {
  width: math.percentage(math.div($span-main, $cols));
}

.side {
  width: math.percentage(math.div($span-side, $cols));
}

.main {
  width: 66.6666666667%;
}

.side {
  width: 33.3333333333%;
}

@use "sass:math";

.names {
  width: math.percentage(0.5);
  min-width: percentage(0.25);
}

.names {
  width: 50%;
  min-width: 25%;
}

🚀 Real-World Use Cases

• Grid / column spans — convert span / columns into % widths.
• Progress and meters — turn 0–1 completion tokens into bar widths.
• Design tokens — keep fractions in maps, emit percentages at the edge.
• Fluid layouts — derive width, flex-basis, or max-width from ratios.
• After math.div — cancel units, then label the ratio as a percent.
• Readable helpers — prefer math.percentage when intent matters more than showing * 100%.

⚠️ Common Pitfalls

• Passing lengths — math.percentage(20px) fails; cancel units first.
• Double-scaling — if the token is already 20 meaning “20 percent,” do not also call percentage (that becomes 2000%).
• Confusing % with unitless — 0.2 is unitless; 20% already has a unit.
• Expecting clamping — values outside 0–1 still convert (2 → 200%).
• Forgetting math.div — length ratios need division before percentage.

💡 Best Practices