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.
math.$pi
- Dart Sass
- since 1.25.0
- LibSass
- ✗
- Ruby Sass
- ✗
Equal to the value of the mathematical constant π.
Bounding Functions permalinkBounding Functions
math.ceil($number)
ceil($number) //=> number
Rounds $number
up to the next highest whole number.
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.
math.floor($number)
floor($number) //=> number
Rounds $number
down to the next lowest whole number.
math.max($number...)
max($number...) //=> number
Returns the highest of one or more numbers.
math.min($number...)
min($number...) //=> number
Returns the lowest of one or more numbers.
math.round($number)
round($number) //=> number
Rounds $number
to the nearest whole number.
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.
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.
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.
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.
math.sqrt($number) //=> number
- Dart Sass
- since 1.25.0
- LibSass
- ✗
- Ruby Sass
- ✗
Returns the square root of $number
.
$number
must be unitless.
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
.
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
.
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
.
math.acos($number) //=> number
- Dart Sass
- since 1.25.0
- LibSass
- ✗
- Ruby Sass
- ✗
Returns the arccosine of $number
in deg
.
$number
must be unitless.
math.asin($number) //=> number
- Dart Sass
- since 1.25.0
- LibSass
- ✗
- Ruby Sass
- ✗
Returns the arcsine of $number
in deg
.
$number
must be unitless.
math.atan($number) //=> number
- Dart Sass
- since 1.25.0
- LibSass
- ✗
- Ruby Sass
- ✗
Returns the arctangent of $number
in deg
.
$number
must be unitless.
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
.
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.
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(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 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%
.
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
.