sass:math

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 permalinkVariables

math.$e

Dart Sass: since 1.25.0
LibSass: ✗
Ruby Sass: ✗

Equal to the value of the mathematical constant e.

SCSS
Sass
SCSS Syntax@debug math.$e; // 2.7182818285
Sass Syntax@debug math.$e // 2.7182818285

math.$pi

Dart Sass: since 1.25.0
LibSass: ✗
Ruby Sass: ✗

Equal to the value of the mathematical constant π.

SCSS
Sass
SCSS Syntax@debug math.$pi; // 3.1415926536
Sass Syntax@debug math.$pi // 3.1415926536

Bounding Functions permalinkBounding Functions

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

Rounds $number up to the next highest whole number.

SCSS
Sass
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

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
Sass
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
Sass
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
Sass
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
Sass
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
Sass
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 permalinkDistance 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
Sass
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

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
Sass
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 permalinkExponential Functions

math.log($number, $base: null) //=> number

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
Sass
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

Dart Sass: since 1.25.0
LibSass: ✗
Ruby Sass: ✗

Raises $base to the power of $exponent.

$base and $exponent must be unitless.

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

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

Dart Sass: since 1.25.0
LibSass: ✗
Ruby Sass: ✗

Returns the square root of $number.

$number must be unitless.

SCSS
Sass
SCSS Syntax@debug math.sqrt(100); // 10
@debug math.sqrt(math.div(1, 3)); // 0.5773502692
@debug math.sqrt(-1); // NaN
Sass Syntax@debug math.sqrt(100) // 10
@debug math.sqrt(math.div(1, 3)) // 0.5773502692
@debug math.sqrt(-1) // NaN

Trigonometric Functions permalinkTrigonometric Functions

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

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
Sass
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

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
Sass
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

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
Sass
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

Dart Sass: since 1.25.0
LibSass: ✗
Ruby Sass: ✗

Returns the arccosine of $number in deg.

$number must be unitless.

SCSS
Sass
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

Dart Sass: since 1.25.0
LibSass: ✗
Ruby Sass: ✗

Returns the arcsine of $number in deg.

$number must be unitless.

SCSS
Sass
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

Dart Sass: since 1.25.0
LibSass: ✗
Ruby Sass: ✗

Returns the arctangent of $number in deg.

$number must be unitless.

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

math.atan2($y, $x) //=> number

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:

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

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

Unit Functions permalinkUnit 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
Sass
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
Sass
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
Sass
SCSS Syntax@debug math.unit(100); // ""
@debug math.unit(100px); // "px"
@debug math.unit(5px * 10px); // "px*px"
@debug math.unit(math.div(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(math.div(5px, 1s))  // "px/s"

Other Functions permalinkOther Functions

math.div($number1, $number2) //=> number

Dart Sass: since 1.33.0
LibSass: ✗
Ruby Sass: ✗

Returns the result of dividing $number1 by $number2.

Any units shared by both numbers will be canceled out. Units in $number1 that aren’t in $number2 will end up in the return value’s numerator, and units in $number2 that aren’t in $number1 will end up in its denominator.

⚠️ Heads up!

For backwards-compatibility purposes, this returns the exact same result as the deprecated / operator, including concatenating two strings with a / character between them. However, this behavior will be removed eventually and shouldn’t be used in new stylesheets.

SCSS
Sass
SCSS Syntax@debug math.div(1, 2); // 0.5
@debug math.div(100px, 5px); // 20
@debug math.div(100px, 5); // 20px
@debug math.div(100px, 5s); // 20px/s
Sass Syntax@debug math.div(1, 2)  // 0.5
@debug math.div(100px, 5px)  // 20
@debug math.div(100px, 5)  // 20px
@debug math.div(100px, 5s)  // 20px/s

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
Sass
SCSS Syntax@debug math.percentage(0.2); // 20%
@debug math.percentage(math.div(100px, 50px)); // 200%
Sass Syntax@debug math.percentage(0.2)  // 20%
@debug math.percentage(math.div(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
Sass
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
Sass
SCSS Syntax@debug math.random(10); // 4
@debug math.random(10000); // 5373
Sass Syntax@debug math.random(10)  // 4
@debug math.random(10000)  // 5373