sass:math

Compatibility:
Dart Sass
since 1.23.0
LibSass
Ruby Sass

Only Dart Sass currently supports loading built-in modules with @use. Users of other implementations must call functions using their global names instead.

Variables

math.$e 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Equal to the value of the mathematical constant e.

SCSS Syntax

@debug math.$e; // 2.7182818285

Sass Syntax

@debug math.$e // 2.7182818285
math.$pi 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Equal to the value of the mathematical constant π.

SCSS Syntax

@debug math.$pi; // 3.1415926536

Sass Syntax

@debug math.$pi // 3.1415926536

Bounding Functions

math.ceil($number)
ceil($number) //=> number 

Rounds $number up to the next highest whole number.

SCSS Syntax

@debug math.ceil(4); // 4
@debug math.ceil(4.2); // 5
@debug math.ceil(4.9); // 5

Sass Syntax

@debug math.ceil(4)  // 4
@debug math.ceil(4.2)  // 5
@debug math.ceil(4.9)  // 5
math.clamp($min, $number, $max) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Restricts $number to the range between $min and $max. If $number is less than $min this returns $min, and if it’s greater than $max this returns $max.

$min, $number, and $max must have compatible units, or all be unitless.

SCSS Syntax

@debug math.clamp(-1, 0, 1); // 0
@debug math.clamp(1px, -1px, 10px); // 1px
@debug math.clamp(-1in, 1cm, 10mm); // 10mm

Sass Syntax

@debug math.clamp(-1, 0, 1) // 0
@debug math.clamp(1px, -1px, 10px) // 1px
@debug math.clamp(-1in, 1cm, 10mm) // 10mm
math.floor($number)
floor($number) //=> number 

Rounds $number down to the next lowest whole number.

SCSS Syntax

@debug math.floor(4); // 4
@debug math.floor(4.2); // 4
@debug math.floor(4.9); // 4

Sass Syntax

@debug math.floor(4)  // 4
@debug math.floor(4.2)  // 4
@debug math.floor(4.9)  // 4
math.max($number...)
max($number...) //=> number 

Returns the highest of one or more numbers.

SCSS Syntax

@debug math.max(1px, 4px); // 4px

$widths: 50px, 30px, 100px;
@debug math.max($widths...); // 100px

Sass Syntax

@debug math.max(1px, 4px)  // 4px

$widths: 50px, 30px, 100px
@debug math.max($widths...)  // 100px
math.min($number...)
min($number...) //=> number 

Returns the lowest of one or more numbers.

SCSS Syntax

@debug math.min(1px, 4px); // 1px

$widths: 50px, 30px, 100px;
@debug math.min($widths...); // 30px

Sass Syntax

@debug math.min(1px, 4px)  // 1px

$widths: 50px, 30px, 100px
@debug math.min($widths...)  // 30px
math.round($number)
round($number) //=> number 

Rounds $number to the nearest whole number.

SCSS Syntax

@debug math.round(4); // 4
@debug math.round(4.2); // 4
@debug math.round(4.9); // 5

Sass Syntax

@debug math.round(4)  // 4
@debug math.round(4.2)  // 4
@debug math.round(4.9)  // 5

Distance Functions

math.abs($number)
abs($number) //=> number 

Returns the absolute value of $number. If $number is negative, this returns -$number, and if $number is positive, it returns $number as-is.

SCSS Syntax

@debug math.abs(10px); // 10px
@debug math.abs(-10px); // 10px

Sass Syntax

@debug math.abs(10px) // 10px
@debug math.abs(-10px) // 10px
math.hypot($number...) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Returns the length of the n-dimensional vector that has components equal to each $number. For example, for three numbers a, b, and c, this returns the square root of a² + b² + c².

The numbers must either all have compatible units, or all be unitless. And since the numbers’ units may differ, the output takes the unit of the first number.

SCSS Syntax

@debug math.hypot(3, 4); // 5

$lengths: 1in, 10cm, 50px;
@debug math.hypot($lengths...); // 4.0952775683in

Sass Syntax

@debug math.hypot(3, 4) // 5

$lengths: 1in, 10cm, 50px
@debug math.hypot($lengths...) // 4.0952775683in

Exponential Functions

math.log($number, $base: null) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Returns the logarithm of $number with respect to $base. If $base is null, the natural log is calculated.

$number and $base must be unitless.

SCSS Syntax

@debug math.log(10); // 2.302585093
@debug math.log(10, 10); // 1

Sass Syntax

@debug math.log(10) // 2.302585093
@debug math.log(10, 10) // 1
math.pow($base, $exponent) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Raises $base to the power of $exponent.

$base and $exponent must be unitless.

SCSS Syntax

@debug math.pow(10, 2); // 100
@debug math.pow(100, 1/3); // 4.6415888336
@debug math.pow(5, -2); // 0.04

Sass Syntax

@debug math.pow(10, 2) // 100
@debug math.pow(100, 1/3) // 4.6415888336
@debug math.pow(5, -2) // 0.04
math.sqrt($number) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Returns the square root of $number.

$number must be unitless.

SCSS Syntax

@debug math.sqrt(100); // 10
@debug math.sqrt(1/3); // 0.5773502692
@debug math.sqrt(-1); // NaN

Sass Syntax

@debug math.sqrt(100) // 10
@debug math.sqrt(1/3) // 0.5773502692
@debug math.sqrt(-1) // NaN

Trigonometric Functions

math.cos($number) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Returns the cosine of $number.

$number must be an angle (its units must be compatible with deg) or unitless. If $number has no units, it is assumed to be in rad.

SCSS Syntax

@debug math.cos(100deg); // -0.1736481777
@debug math.cos(1rad); // 0.5403023059
@debug math.cos(1); // 0.5403023059

Sass Syntax

@debug math.cos(100deg) // -0.1736481777
@debug math.cos(1rad) // 0.5403023059
@debug math.cos(1) // 0.5403023059
math.sin($number) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Returns the sine of $number.

$number must be an angle (its units must be compatible with deg) or unitless. If $number has no units, it is assumed to be in rad.

SCSS Syntax

@debug math.sin(100deg); // 0.984807753
@debug math.sin(1rad); // 0.8414709848
@debug math.sin(1); // 0.8414709848

Sass Syntax

@debug math.sin(100deg) // 0.984807753
@debug math.sin(1rad) // 0.8414709848
@debug math.sin(1) // 0.8414709848
math.tan($number) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Returns the tangent of $number.

$number must be an angle (its units must be compatible with deg) or unitless. If $number has no units, it is assumed to be in rad.

SCSS Syntax

@debug math.tan(100deg); // -5.6712818196
@debug math.tan(1rad); // 1.5574077247
@debug math.tan(1); // 1.5574077247

Sass Syntax

@debug math.tan(100deg) // -5.6712818196
@debug math.tan(1rad) // 1.5574077247
@debug math.tan(1) // 1.5574077247
math.acos($number) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Returns the arccosine of $number in deg.

$number must be unitless.

SCSS Syntax

@debug math.acos(0.5); // 60deg
@debug math.acos(2); // NaNdeg

Sass Syntax

@debug math.acos(0.5) // 60deg
@debug math.acos(2) // NaNdeg
math.asin($number) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Returns the arcsine of $number in deg.

$number must be unitless.

SCSS Syntax

@debug math.asin(0.5); // 30deg
@debug math.asin(2); // NaNdeg

Sass Syntax

@debug math.asin(0.5) // 30deg
@debug math.asin(2) // NaNdeg
math.atan($number) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Returns the arctangent of $number in deg.

$number must be unitless.

SCSS Syntax

@debug math.atan(10); // 84.2894068625deg

Sass Syntax

@debug math.atan(10) // 84.2894068625deg
math.atan2($y, $x) //=> number 
Compatibility:
Dart Sass
since 1.25.0
LibSass
Ruby Sass

Returns the 2-argument arctangent of $y and $x in deg.

$y and $x must have compatible units or be unitless.

💡 Fun fact:

atan2($y, $x) is distinct from atan($y / $x) because it preserves the quadrant of the point in question. For example, atan2(1, -1) corresponds to the point (-1, 1) and returns 135deg. In contrast, atan(1 / -1) and atan(-1 / 1) resolve first to atan(-1), so both return -45deg.

SCSS Syntax

@debug math.atan2(-1, 1); // 135deg

Sass Syntax

@debug math.atan2(-1, 1) // 135deg

Unit Functions

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

Returns whether $number1 and $number2 have compatible units.

If this returns true, $number1 and $number2 can safely be added, subtracted, and compared. Otherwise, doing so will produce errors.

⚠️ Heads up!

The global name of this function is comparable, but when it was added to the sass:math module the name was changed to compatible to more clearly convey what the function does.

SCSS Syntax

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

Sass Syntax

@debug math.compatible(2px, 1px)  // true
@debug math.compatible(100px, 3em)  // false
@debug math.compatible(10cm, 3mm)  // true
math.is-unitless($number)
unitless($number) //=> boolean 

Returns whether $number has no units.

SCSS Syntax

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

Sass Syntax

@debug math.is-unitless(100)  // true
@debug math.is-unitless(100px)  // false
math.unit($number)
unit($number) //=> quoted string 

Returns a string representation of $number’s units.

⚠️ Heads up!

This function is intended for debugging; its output format is not guaranteed to be consistent across Sass versions or implementations.

SCSS Syntax

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

Sass Syntax

@debug math.unit(100)  // ""
@debug math.unit(100px)  // "px"
@debug math.unit(5px * 10px)  // "px*px"
@debug math.unit(5px / 1s)  // "px/s"

Other Functions

math.percentage($number)
percentage($number) //=> number 

Converts a unitless $number (usually a decimal between 0 and 1) to a percentage.

💡 Fun fact:

This function is identical to $number * 100%.

SCSS Syntax

@debug math.percentage(0.2); // 20%
@debug math.percentage(100px / 50px); // 200%

Sass Syntax

@debug math.percentage(0.2)  // 20%
@debug math.percentage(100px / 50px)  // 200%
math.random($limit: null)
random($limit: null) //=> number 

If $limit is null, returns a random decimal number between 0 and 1.

SCSS Syntax

@debug math.random(); // 0.2821251858
@debug math.random(); // 0.6221325814

Sass Syntax

@debug math.random()  // 0.2821251858
@debug math.random()  // 0.6221325814

If $limit is a number greater than or equal to 1, returns a random whole number between 1 and $limit.

SCSS Syntax

@debug math.random(10); // 4
@debug math.random(10000); // 5373

Sass Syntax

@debug math.random(10)  // 4
@debug math.random(10000)  // 5373