16 KiB
Functions
Table of Contents
Definitions
Special Number
A special number is either:
- a calculation, or
- an unquoted string that CSS will recognize as a function that may return a
number. For the purposes of Sass, this is any unquoted string that begins with
calc(
,var(
,env(
,clamp(
,min(
, ormax(
. This matching is case-insensitive.
Sass functions that shadow CSS functions must work with any invocation that CSS allows, which includes allowing special numbers anywhere a number would be allowed.
Special Variable String
A special variable string is special number that begins with var(
. This
matching is case-insensitive.
Unlike other special numbers, variables can expand into multiple arguments to a single function.
Syntax
FunctionExpression¹ ::= SpecialFunctionExpression | EmptyFallbackVar | FunctionCall EmptyFallbackVar² ::= 'var(' Expression ',' ')' FunctionCall⁴ ::= NamespacedIdentifier ArgumentInvocation
1: Both CssMinMax
and EmptyFallbackVar
take precedence over FunctionCall
if either could be consumed.
2: 'var('
is matched case-insensitively.
4: FunctionCall
may not have any whitespace between the NamespacedIdentifier
and the ArgumentInvocation
. It may not start with SpecialFunctionName
,
'calc('
, or 'clamp('
(case-insensitively).
FunctionCall ::= NamespacedIdentifier ArgumentInvocation
No whitespace is allowed between the NamespacedIdentifier
and the
ArgumentInvocation
in FunctionCall
.
Semantics
EmptyFallbackVar
To evaluate an EmptyFallbackVar
call
:
-
Let
argument
be the result of evaluatingcall
'sExpression
. -
Let
function
be the result of resolving a function named'var'
. -
If
function
is null, return an unquoted string consisting of'var('
followed byargument
's CSS representation followed by',)'
. -
Return the result of calling
function
withargument
as its first argument and an empty unquoted string as its second argument.
FunctionCall
To evaluate a FunctionCall
call
:
-
Let
name
becall
'sNamespacedIdentifier
. -
Let
function
be the result of resolving a function namedname
. -
If
function
is null andname
is not a plainIdentifier
, throw an error. -
If
function
is null;name
is case-insensitively equal to"min"
,"max"
,"round"
, or"abs"
;call
'sArgumentInvocation
doesn't have anyKeywordArgument
s orRestArgument
s; and all arguments incall
'sArgumentInvocation
are calculation-safe, return the result of evaluatingcall
as a calculation.For calculation functions that overlap with global Sass function names, we want anything Sass-specific like this to end up calling the Sass function. For all other calculation functions, we want those constructs to throw an error (which they do when evaluating
call
as a calculation). -
If
function
is null andname
is case-insensitively equal to"calc"
,"clamp"
,"hypot"
,"sin"
,"cos"
,"tan"
,"asin"
,"acos"
,"atan"
,"sqrt"
,"exp"
,"sign"
,"mod"
,"rem"
,"atan2"
,"pow"
, or"log"
, return the result of evaluatingcall
as a calculation. -
If
function
is null, set it to the global function namedname
. -
If
function
is still null:-
Let
list
be the result of evaluatingcall
'sArgumentInvocation
. -
If
list
has keywords, throw an error. -
Return an unquoted string representing a CSS function call with name
name
and argumentslist
.
-
-
Execute
call
'sArgumentInvocation
withfunction
'sArgumentDeclaration
infunction
's scope. -
Execute each statement in
function
until aReturnRule
return
that's lexically contained infunction
'sStatements
is encountered. If no such statement is encountered, throw an error. -
Evaluate
return
'sExpression
and return the result.
Global Functions
While most built-in Sass functions are defined in built-in modules, a few are globally available with no
@use
necessary. These are mostly functions that expand upon the behavior of plain CSS functions.In addition, many functions that are defined in built-in modules have global aliases for backwards-compatibility with stylesheets written before
@use
was introduced. These global aliases should be avoided by stylesheet authors if possible.
adjust-hue()
adjust-hue($color, $degrees)
-
If
$color
isn't a color or$degrees
isn't a number, throw an error. -
Let
degrees
be the result of converting$degrees
todeg
allowing unitless. -
Let
saturation
andlightness
be the result of callingcolor.saturation($color)
andcolor.lightness($color)
, respectively. -
Return the result of calling
hsl()
withdegree
,saturation
,lightness
, and$color
's alpha channel.
alpha()
-
alpha($color)
-
If
$color
is not a string, call the other overload and return its result. -
Return the alpha channel of
$color
as a unitless number.
-
-
alpha($args...)
This overload exists to support Microsoft's proprietary
alpha()
function.-
If
$args
is empty, throw an error. -
If
$args
has any keyword arguments, throw an error. -
Unless all arguments of
$args
are unquoted strings that begin with a sequence of ASCII letters, followed by one or more spaces, followed by=
throw an error. -
Return a plain CSS function string with the name
"alpha"
and the arguments$args
.
-
rgb()
and rgba()
The rgba()
function is identical to rgb()
, except that if it would return a
plain CSS function named "rgb"
that function is named "rgba"
instead.
-
rgb($red, $green, $blue, $alpha)
-
If any argument is a special number, return a plain CSS function string with the name
"rgb"
and the arguments$red
,$green
,$blue
, and$alpha
. -
If any of
$red
,$green
,$blue
, or$alpha
aren't numbers, throw an error. -
Let
red
,green
, andblue
be the result of percent-converting$red
,$green
, and$blue
, respectively, with amax
of 255. -
Let
alpha
be the result of percent-converting$alpha
with amax
of 1. -
Return a color with the given
red
,green
,blue
, andalpha
channels.
-
-
rgb($red, $green, $blue)
-
If any argument is a special number, return a plain CSS function string with the name
"rgb"
and the arguments$red
,$green
, and$blue
. -
Otherwise, return the result of calling
rgb()
with$red
,$green
,$blue
, and1
.
-
-
rgb($color, $alpha)
-
If either argument is a special variable string, return a plain CSS function string with the name
"rgb"
and the same arguments. -
If
$color
isn't a color, throw an error. -
Call
rgb()
with$color
's red, green, and blue channels as unitless number arguments, and with$alpha
as the final argument. Return the result.
-
-
rgb($channels)
-
If
$channels
is a special variable string, return a plain CSS function string with the name"rgb"
and the argument$channels
. -
If
$channels
is an unbracketed slash-separated list:-
If
$channels
doesn't have exactly two elements, throw an error. Otherwise, letrgb
be the first element andalpha
the second element. -
If either
rgb
oralpha
is a special variable string, return a plain CSS function string with the name"rgb"
and the argument$channels
. -
If
rgb
is not an unbracketed space-separated list, throw an error. -
If the first element of
rgb
is an unquoted string which is case-insensitively equal tofrom
, return a plain CSS function string with the name"rgb"
and the argument$channels
. -
If
rgb
has more than three elements, throw an error. -
If
rgb
has fewer than three elements:-
If any element of
rgb
is a special variable string, return a plain CSS function string with the name"rgb"
and the argument$channels
. -
Otherwise, throw an error.
-
-
Let
red
,green
, andblue
be the three elements ofrgb
. -
Call
rgb()
withred
,green
,blue
, andalpha
as arguments and return the result.
-
-
Otherwise, if
$channels
is not an unbracketed space-separated list, throw an error. -
If the first element of
$channels
is an unquoted string which is case-insensitively equal tofrom
, return a plain CSS function string with the name"rgb"
and the argument$channels
. -
If
$channels
has more than three elements, throw an error. -
If
$channels
has fewer than three elements:-
If any element of
$channels
is a special variable string, return a plain CSS function string with the name"rgb"
and the argument$channels
. -
If the last element of
$channels
is an unquoted string that begins withvar(
and contains/
, return a plain CSS function string with the name"rgb"
and the argument$channels
. -
Otherwise, throw an error.
-
-
Let
red
andgreen
be the first two elements of$channels
. -
If the third element of
$channels
is an unquoted string that contains/
:- Return a plain CSS function string with the name
"rgb"
and the argument$channels
.
- Return a plain CSS function string with the name
-
Otherwise, if the third element of
$channels
has preserved its status as two slash-separated numbers:- Let
blue
be the number before the slash andalpha
the number after the slash.
- Let
-
Otherwise:
- Let
blue
be the third element of$channels
.
- Let
-
Call
rgb()
withred
,green
,blue
, andalpha
(if it's defined) as arguments and return the result.
-
hsl()
and hsla()
The hsla()
function is identical to hsl()
, except that if it would return a
plain CSS function named "hsl"
that function is named "hsla"
instead.
-
hsl($hue, $saturation, $lightness, $alpha: 1)
-
If any argument is a special number, return a plain CSS function string with the name
"hsl"
and the arguments$hue
,$saturation
,$lightness
, and$alpha
. -
If any of
$hue
,$saturation
,$lightness
, or$alpha
aren't numbers, throw an error. -
Let
hue
be the result of converting$hue
todeg
allowing unitless. -
If
$saturation
and$lightness
don't have unit%
, throw an error. -
Let
saturation
andlightness
be the result of clamping$saturation
and$lightness
, respectively, between0%
and100%
and dividing by100%
. -
Let
red
,green
, andblue
be the result of convertinghue
,saturation
, andlightness
to RGB. -
Set
red
,green
, andblue
to their existing values multiplied by 255 and rounded to the nearest integers. -
Let
alpha
be the result of percent-converting$alpha
with amax
of 1. -
Return a color with the given
red
,green
,blue
, andalpha
channels.
-
-
hsl($hue, $saturation, $lightness)
-
If any argument is a special number, return a plain CSS function string with the name
"hsl"
and the arguments$hue
,$saturation
, and$lightness
. -
Otherwise, return the result of calling
hsl()
with$hue
,$saturation
,$lightness
, and1
.
-
-
hsl($hue, $saturation)
-
If either argument is a special variable string, return a plain CSS function string with the name
"hsl"
and the same arguments. -
Otherwise, throw an error.
-
-
hsl($channels)
-
If
$channels
is a special variable string, return a plain CSS function string with the name"hsl"
and the argument$channels
. -
If
$channels
is an unbracketed slash-separated list:-
If
$channels
doesn't have exactly two elements, throw an error. Otherwise, lethsl
be the first element andalpha
the second element. -
If either
hsl
oralpha
is a special variable string, return a plain CSS function string with the name"hsl"
and the argument$channels
. -
If
hsl
is not an unbracketed space-separated list, throw an error. -
If the first element of
hsl
is an unquoted string which is case-insensitively equal tofrom
, return a plain CSS function string with the name"hsl"
and the argument$channels
. -
If
hsl
has more than three elements, throw an error. -
If
hsl
has fewer than three elements:-
If any element of
hsl
is a special variable string, return a plain CSS function string with the name"hsl"
and the argument$channels
. -
Otherwise, throw an error.
-
-
Let
hue
,saturation
, andlightness
be the three elements ofhsl
. -
Call
hsl()
withhue
,saturation
,lightness
, andalpha
as arguments and return the result.
-
-
Otherwise, if
$channels
is not an unbracketed space-separated list, throw an error. -
If the first element of
$channels
is an unquoted string which is case-insensitively equal tofrom
, return a plain CSS function string with the name"hsl"
and the argument$channels
. -
If
$channels
has more than three elements, throw an error. -
If
$channels
has fewer than three elements:-
If any element of
$channels
is a special variable string, return a plain CSS function string with the name"hsl"
and the argument$channels
. -
If the last element of
$channels
is an unquoted string that begins withvar(
and contains/
, return a plain CSS function string with the name"hsl"
and the argument$channels
. -
Otherwise, throw an error.
-
-
Let
hue
andsaturation
be the first two elements of$channels
. -
If the third element of
$channels
is an unquoted string that contains/
:- Return a plain CSS function string with the name
"rgb"
and the argument$channels
.
- Return a plain CSS function string with the name
-
Otherwise, if the third element of
$channels
has preserved its status as two slash-separated numbers:- Let
lightness
be the number before the slash andalpha
the number after the slash.
- Let
-
Otherwise:
- Let
lightness
be the third element of$channels
.
- Let
-
Call
hsl()
withhue
,saturation
,lightness
, andalpha
(if it's defined) as arguments and return the result.
-
if()
if($condition, $if-true, $if-false)