Sass Functions
Numeric Operators
Sass supports the standard set of mathematical operators for numbers. They automatically convert between compatible units.
-
<expression> + <expression>
adds the first expression’s value to the second’s. -
<expression> - <expression>
subtracts the first expression’s value from the second’s. -
<expression> * <expression>
multiplies the first expression’s value by the second’s. -
<expression> / <expression>
divides the first expression’s value by the second’s. -
<expression> % <expression>
returns the remainder of the first expression’s value divided by the second’s. This is known as the modulo operator.
@debug 10s + 15s; // 25s
@debug 1in - 10px; // 0.8958333333in
@debug 5px * 3px; // 15px*px
@debug (12px/4px); // 3
@debug 1in % 9px; // 0.0625in
@debug 10s + 15s // 25s
@debug 1in - 10px // 0.8958333333in
@debug 5px * 3px // 15px*px
@debug (12px/4px) // 3
@debug 1in % 9px // 0.0625in
Unitless numbers can be used with numbers of any unit.
@debug 100px + 50; // 150px
@debug 4s * 10; // 40s
@debug 100px + 50 // 150px
@debug 4s * 10 // 40s
Numbers with incompatible units can’t be used with addition, subtraction, or modulo.
@debug 100px + 10s;
// ^^^^^^^^^^^
// Error: Incompatible units px and s.
@debug 100px + 10s
// ^^^^^^^^^^^
// Error: Incompatible units px and s.
Unary Operators
You can also write +
and -
as unary operators, which take only one value:
-
+<expression>
returns the expression’s value without changing it. -
-<expression>
returns the negative version of the expression’s value.
@debug +(5s + 7s); // 12s
@debug -(50px + 30px); // -80px
@debug -(10px - 15px); // 5px
@debug +(5s + 7s) // 12s
@debug -(50px + 30px) // -80px
@debug -(10px - 15px) // 5px
⚠️ Heads up!
Because -
can refer to both subtraction and unary negation, it can be confusing which is which in a space-separated list. To be safe:
- Always write spaces on both sides of
-
when subtracting. - Write a space before
-
but not after for a negative number or a unary negation. - Wrap unary negation in parentheses if it’s in a space-separated list.
The different meanings of -
in Sass take precedence in the following order:
-
-
as part of an identifier. The only exception are units; Sass normally allows any valid identifier to be used as an identifier, but units may not contain a hyphen followed by a digit. -
-
between an expression and a literal number with no whitespace, which is parsed as subtraction. -
-
at the beginning of a literal number, which is parsed as a negative number. -
-
between two numbers regardless of whitespace, which is parsed as subtraction. -
-
before a value other than a literal number, which is parsed as unary negation.
@debug a-1; // a-1
@debug 5px-3px; // 2px
@debug 5-3; // 2
@debug 1 -2 3; // 1 -2 3
$number: 2;
@debug 1 -$number 3; // -1 3
@debug 1 (-$number) 3; // 1 -2 3
@debug a-1 // a-1
@debug 5px-3px // 2px
@debug 5-3 // 2
@debug 1 -2 3 // 1 -2 3
$number: 2
@debug 1 -$number 3 // -1 3
@debug 1 (-$number) 3 // 1 -2 3
Slash-Separated Values
A few CSS properties support /
as a way of separating values. This means Sass has to disambiguate between /
as a property value and /
as division. In order to make this work, if two numbers are separated by /
, Sass will print the result as slash-separated instead of divided unless one of these conditions is met:
- Either expression is anything other than a literal number.
- The result is stored in a variable or returned by a function.
- The operation is surrounded by parentheses, unless those parentheses are outside a list that contains the operation.
- The result is used as part of another operation (other than
/
).
If you want to force /
to be used as a separator, you can write it as #{<expression>} / #{<expression>}
.
@debug 15px / 30px; // 15px/30px
@debug (10px + 5px) / 30px; // 0.5
@debug #{10px + 5px} / 30px; // 15px/30px
$result: 15px / 30px;
@debug $result; // 0.5
@function fifteen-divided-by-thirty() {
@return 15px / 30px;
}
@debug fifteen-divided-by-thirty(); // 0.5
@debug (15px/30px); // 0.5
@debug (bold 15px/30px sans-serif); // bold 15px/30px sans-serif
@debug 15px/30px + 1; // 1.5
@debug 15px / 30px // 15px/30px
@debug (10px + 5px) / 30px // 0.5
$result: 15px / 30px
@debug $result // 0.5
@function fifteen-divided-by-thirty()
@return 15px / 30px
@debug fifteen-divided-by-thirty() // 0.5
@debug (15px/30px) // 0.5
@debug (bold 15px/30px sans-serif) // bold 15px/30px sans-serif
@debug 15px/30px + 1 // 1.5
Units
Sass has powerful support for manipulating units based on how real-world unit calculations work. When two numbers are multiplied, their units are multiplied as well. When one number is divided by another, the result takes its numerator units from the first number and its denominator units from the second. A number can have any number of units in the numerator and/or denominator.
@debug 4px * 6px; // 24px*px (read "square pixels")
@debug 5px / 2s; // 2.5px/s (read "pixels per second")
@debug 5px * 30deg / 2s / 24em; // 3.125px*deg/s*em
// (read "pixel-degrees per second-em")
$degrees-per-second: 20deg/1s;
@debug $degrees-per-second; // 20deg/s
@debug 1 / $degrees-per-second; // 0.05s/deg
@debug 4px * 6px // 24px*px (read "square pixels")
@debug 5px / 2s // 2.5px/s (read "pixels per second")
@debug 5px * 30deg / 2s / 24em // 3.125px*deg/s*em
// (read "pixel-degrees per second-em")
$degrees-per-second: 20deg/1s
@debug $degrees-per-second // 20deg/s
@debug 1 / $degrees-per-second // 0.05s/deg
⚠️ Heads up!
Because CSS doesn’t support complex units like square pixels, using a number with complex units as a property value will produce an error. This is a feature in disguise, though; if you aren’t ending up with the right unit, it usually means that something’s wrong with your calculations! And remember, you can always use the @debug
rule to check out the units of any variable or expression.
Sass will automatically convert between compatible units, although which unit it will choose for the result depends on which implementation of Sass you’re using.If you try to combine incompatible units, like 1in + 1em
, Sass will throw an error.
// CSS defines one inch as 96 pixels.
@debug 1in + 6px; // 102px or 1.0625in
@debug 1in + 1s;
// ^^^^^^^^
// Error: Incompatible units s and in.
// CSS defines one inch as 96 pixels.
@debug 1in + 6px // 102px or 1.0625in
@debug 1in + 1s
// ^^^^^^^^
// Error: Incompatible units s and in.
As in real-world unit calculations, if the numerator contains units that are compatible with units in the denominator (like 96px / 1in
), they’ll cancel out. This makes it easy to define a ratio that you can use for converting between units. In the example below, we set the desired speed to one second per 50 pixels, and then multiply that by the number of pixels the transition covers to get the time it should take.
$transition-speed: 1s/50px;
@mixin move($left-start, $left-stop) {
position: absolute;
left: $left-start;
transition: left ($left-stop - $left-start) * $transition-speed;
&:hover {
left: $left-stop;
}
}
.slider {
@include move(10px, 120px);
}
$transition-speed: 1s/50px
@mixin move($left-start, $left-stop)
position: absolute
left: $left-start
transition: left ($left-stop - $left-start) * $transition-speed
&:hover
left: $left-stop
.slider
@include move(10px, 120px)
.slider {
position: absolute;
left: 10px;
transition: left 2.2s;
}
.slider:hover {
left: 120px;
}
⚠️ Heads up!
If your arithmetic gives you the wrong unit, you probably need to check your math. You may be leaving off units for a quantity that should have them! Staying unit-clean allows Sass to give you helpful errors when something isn’t right.
You should especially avoid using interpolation like #{$number}px
. This doesn’t actually create a number! It creates an unquoted string that looks like a number, but won’t work with any number operations or functions. Try to make your math unit-clean so that $number
already has the unit px
, or write $number * 1px
.
⚠️ Heads up!
Percentages in Sass work just like every other unit. They are not interchangeable with decimals, because in CSS decimals and percentages mean different things. For example, 50%
is a number with %
as its unit, and Sass considers it different than the number 0.5
.
You can convert between decimals and percentages using unit arithmetic. $percentage / 100%
will return the corresponding decimal, and $decimal *
100%
will return the corresponding percentage. You can also use the math.percentage()
function as a more explicit way of writing $decimal *
100%
.
© 2006–2020 Hampton Catlin, Nathan Weizenbaum, and Chris Eppstein
Licensed under the MIT License.
https://sass-lang.com/documentation/operators/numeric