mirror of
https://github.com/danog/sass-site.git
synced 2024-12-13 09:57:35 +01:00
273 lines
11 KiB
Plaintext
273 lines
11 KiB
Plaintext
---
|
|
title: Built-In Modules
|
|
eleventyComputed:
|
|
before_introduction: >
|
|
{% render 'doc_snippets/built-in-module-status' %}
|
|
introduction: >
|
|
Sass provides many built-in modules which contain useful functions (and the
|
|
occasional mixin). These modules can be loaded with the [`@use`
|
|
rule](/documentation/at-rules/use) like any user-defined stylesheet, and their
|
|
functions can be called [like any other module
|
|
member](/documentation/at-rules/use#loading-members). All built-in module URLs
|
|
begin with `sass:` to indicate that they're part of Sass itself.
|
|
---
|
|
|
|
{% headsUp %}
|
|
Before the Sass module system was introduced, all Sass functions were globally
|
|
available at all times. Many functions still have global aliases (these are
|
|
listed in their documentation). The Sass team discourages their use and will
|
|
eventually deprecate them, but for now they remain available for compatibility
|
|
with older Sass versions and with LibSass (which doesn't support the module
|
|
system yet).
|
|
|
|
[A few functions][] are *only* available globally even in the new module
|
|
system, either because they have special evaluation behavior ([`if()`][]) or
|
|
because they add extra behavior on top of built-in CSS functions ([`rgb()`][]
|
|
and [`hsl()`][]). These will not be deprecated and can be used freely.
|
|
|
|
[a few functions]: #global-functions
|
|
[`if()`]: #if
|
|
[`rgb()`]: #rgb
|
|
[`hsl()`]: #hsl
|
|
{% endheadsUp %}
|
|
|
|
{% codeExample 'modules' %}
|
|
@use "sass:color";
|
|
|
|
.button {
|
|
$primary-color: #6b717f;
|
|
color: $primary-color;
|
|
border: 1px solid color.scale($primary-color, $lightness: 20%);
|
|
}
|
|
===
|
|
@use "sass:color"
|
|
|
|
.button
|
|
$primary-color: #6b717f
|
|
color: $primary-color
|
|
border: 1px solid color.scale($primary-color, $lightness: 20%)
|
|
===
|
|
.button {
|
|
color: #6b717f;
|
|
border: 1px solid #878d9a;
|
|
}
|
|
{% endcodeExample %}
|
|
|
|
{% markdown %}
|
|
Sass provides the following built-in modules:
|
|
|
|
* The [`sass:math` module][] provides functions that operate on [numbers][].
|
|
|
|
* The [`sass:string` module][] makes it easy to combine, search, or split
|
|
apart [strings][].
|
|
|
|
* The [`sass:color` module][] generates new [colors][] based on existing ones,
|
|
making it easy to build color themes.
|
|
|
|
* The [`sass:list` module][] lets you access and modify values in [lists][].
|
|
|
|
* The [`sass:map` module][] makes it possible to look up the value associated
|
|
with a key in a [map][], and much more.
|
|
|
|
* The [`sass:selector` module][] provides access to Sass's powerful selector
|
|
engine.
|
|
|
|
* The [`sass:meta` module][] exposes the details of Sass's inner workings.
|
|
|
|
[`sass:math` module]: /documentation/modules/math
|
|
[numbers]: /documentation/values/numbers
|
|
[`sass:string` module]: /documentation/modules/string
|
|
[strings]: /documentation/values/strings
|
|
[`sass:color` module]: /documentation/modules/color
|
|
[colors]: /documentation/values/colors
|
|
[`sass:list` module]: /documentation/modules/list
|
|
[lists]: /documentation/values/lists
|
|
[`sass:map` module]: /documentation/modules/map
|
|
[map]: /documentation/values/maps
|
|
[`sass:selector` module]: /documentation/modules/selector
|
|
[`sass:meta` module]: /documentation/modules/meta
|
|
|
|
## Global Functions
|
|
{% endmarkdown %}
|
|
|
|
{% function 'hsl($hue $saturation $lightness)', 'hsl($hue $saturation $lightness / $alpha)', 'hsl($hue, $saturation, $lightness, $alpha: 1)', 'hsla($hue $saturation $lightness)', 'hsla($hue $saturation $lightness / $alpha)', 'hsla($hue, $saturation, $lightness, $alpha: 1)', 'returns:color' %}
|
|
{% compatibility 'dart: "1.15.0"', 'libsass: false', 'ruby: false', 'feature: "Level 4 Syntax"' %}
|
|
LibSass and Ruby Sass only support the following signatures:
|
|
|
|
* `hsl($hue, $saturation, $lightness)`
|
|
* `hsla($hue, $saturation, $lightness, $alpha)`
|
|
|
|
Note that for these implementations, the `$alpha` argument is *required* if
|
|
the function name `hsla()` is used, and *forbidden* if the function name
|
|
`hsl()` is used.
|
|
{% endcompatibility %}
|
|
|
|
{% compatibility 'dart: true', 'libsass: false', 'ruby: "3.7.0"', 'feature: "Percent Alpha"' %}
|
|
LibSass and older versions of Ruby Sass don't support alpha values specified
|
|
as percentages.
|
|
{% endcompatibility %}
|
|
|
|
{% markdown %}
|
|
Returns a color with the given [hue, saturation, and lightness][] and the
|
|
given alpha channel.
|
|
|
|
[hue, saturation, and lightness]: https://en.wikipedia.org/wiki/HSL_and_HSV
|
|
|
|
The hue is a number between `0deg` and `360deg` (inclusive) and may be
|
|
unitless. The saturation and lightness are numbers between `0%` and `100%`
|
|
(inclusive) and may *not* be unitless. The alpha channel can be specified as
|
|
either a unitless number between 0 and 1 (inclusive), or a percentage
|
|
between `0%` and `100%` (inclusive).
|
|
{% endmarkdown %}
|
|
|
|
{% funFact false %}
|
|
{% markdown %}
|
|
You can pass [special functions][] like `calc()` or `var()` in place of
|
|
any argument to `hsl()`. You can even use `var()` in place of multiple
|
|
arguments, since it might be replaced by multiple values! When a color
|
|
function is called this way, it returns an unquoted string using the same
|
|
signature it was called with.
|
|
|
|
[special functions]: /documentation/syntax/special-functions
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'hsl-special', false %}
|
|
@debug hsl(210deg 100% 20% / var(--opacity)); // hsl(210deg 100% 20% / var(--opacity))
|
|
@debug hsla(var(--peach), 20%); // hsla(var(--peach), 20%)
|
|
===
|
|
@debug hsl(210deg 100% 20% / var(--opacity)) // hsl(210deg 100% 20% / var(--opacity))
|
|
@debug hsla(var(--peach), 20%) // hsla(var(--peach), 20%)
|
|
{% endcodeExample %}
|
|
{% endfunFact %}
|
|
|
|
{% headsUp %}
|
|
Sass's [special parsing rules][] for slash-separated values make it
|
|
difficult to pass variables for `$lightness` or `$alpha` when using the
|
|
`hsl($hue $saturation $lightness / $alpha)` signature. Consider using
|
|
`hsl($hue, $saturation, $lightness, $alpha)` instead.
|
|
|
|
[special parsing rules]: /documentation/operators/numeric#slash-separated-values
|
|
{% endheadsUp %}
|
|
|
|
{% codeExample 'hsl', false %}
|
|
@debug hsl(210deg 100% 20%); // #036
|
|
@debug hsl(34, 35%, 92%); // #f2ece4
|
|
@debug hsl(210deg 100% 20% / 50%); // rgba(0, 51, 102, 0.5)
|
|
@debug hsla(34, 35%, 92%, 0.2); // rgba(242, 236, 228, 0.2)
|
|
===
|
|
@debug hsl(210deg 100% 20%) // #036
|
|
@debug hsl(34, 35%, 92%) // #f2ece4
|
|
@debug hsl(210deg 100% 20% / 50%) // rgba(0, 51, 102, 0.5)
|
|
@debug hsla(34, 35%, 92%, 0.2) // rgba(242, 236, 228, 0.2)
|
|
{% endcodeExample %}
|
|
{% endfunction %}
|
|
|
|
{% function 'if($condition, $if-true, $if-false)' %}
|
|
{% markdown %}
|
|
Returns `$if-true` if `$condition` is [truthy][], and `$if-false` otherwise.
|
|
|
|
This function is special in that it doesn't even evaluate the argument that
|
|
isn't returned, so it's safe to call even if the unused argument would throw
|
|
an error.
|
|
|
|
[truthy]: /documentation/at-rules/control/if#truthiness-and-falsiness
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'debug', false %}
|
|
@debug if(true, 10px, 15px); // 10px
|
|
@debug if(false, 10px, 15px); // 15px
|
|
@debug if(variable-defined($var), $var, null); // null
|
|
===
|
|
@debug if(true, 10px, 15px) // 10px
|
|
@debug if(false, 10px, 15px) // 15px
|
|
@debug if(variable-defined($var), $var, null) // null
|
|
{% endcodeExample %}
|
|
{% endfunction %}
|
|
|
|
{% function 'rgb($red $green $blue)', 'rgb($red $green $blue / $alpha)', 'rgb($red, $green, $blue, $alpha: 1)', 'rgb($color, $alpha)', 'rgba($red $green $blue)', 'rgba($red $green $blue / $alpha)', 'rgba($red, $green, $blue, $alpha: 1)', 'rgba($color, $alpha)', 'returns:color' %}
|
|
{% compatibility 'dart: "1.15.0"', 'libsass: false', 'ruby: false', 'feature: "Level 4 Syntax"' %}
|
|
LibSass and Ruby Sass only support the following signatures:
|
|
|
|
* `rgb($red, $green, $blue)`
|
|
* `rgba($red, $green, $blue, $alpha)`
|
|
* `rgba($color, $alpha)`
|
|
|
|
Note that for these implementations, the `$alpha` argument is *required* if
|
|
the function name `rgba()` is used, and *forbidden* if the function name
|
|
`rgb()` is used.
|
|
{% endcompatibility %}
|
|
|
|
{% compatibility 'dart: true', 'libsass: false', 'ruby: "3.7.0"', 'feature: "Percent Alpha"' %}
|
|
LibSass and older versions of Ruby Sass don't support alpha values specified
|
|
as percentages.
|
|
{% endcompatibility %}
|
|
|
|
{% markdown %}
|
|
If `$red`, `$green`, `$blue`, and optionally `$alpha` are passed, returns a
|
|
color with the given red, green, blue, and alpha channels.
|
|
|
|
Each channel can be specified as either a [unitless][] number between 0 and
|
|
255 (inclusive), or a percentage between `0%` and `100%` (inclusive). The
|
|
alpha channel can be specified as either a unitless number between 0 and 1
|
|
(inclusive), or a percentage between `0%` and `100%` (inclusive).
|
|
|
|
[unitless]: /documentation/values/numbers#units
|
|
{% endmarkdown %}
|
|
|
|
{% funFact false %}
|
|
{% markdown %}
|
|
You can pass [special functions][] like `calc()` or `var()` in place of
|
|
any argument to `rgb()`. You can even use `var()` in place of multiple
|
|
arguments, since it might be replaced by multiple values! When a color
|
|
function is called this way, it returns an unquoted string using the same
|
|
signature it was called with.
|
|
|
|
[special functions]: /documentation/syntax/special-functions
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'rgb-special', false %}
|
|
@debug rgb(0 51 102 / var(--opacity)); // rgb(0 51 102 / var(--opacity))
|
|
@debug rgba(var(--peach), 0.2); // rgba(var(--peach), 0.2)
|
|
===
|
|
@debug rgb(0 51 102 / var(--opacity)) // rgb(0 51 102 / var(--opacity))
|
|
@debug rgba(var(--peach), 0.2) // rgba(var(--peach), 0.2)
|
|
{% endcodeExample %}
|
|
{% endfunFact %}
|
|
|
|
{% headsUp %}
|
|
Sass's [special parsing rules][] for slash-separated values make it
|
|
difficult to pass variables for `$blue` or `$alpha` when using the
|
|
`rgb($red $green $blue / $alpha)` signature. Consider using
|
|
`rgb($red, $green, $blue, $alpha)` instead.
|
|
|
|
[special parsing rules]: /documentation/operators/numeric#slash-separated-values
|
|
{% endheadsUp %}
|
|
|
|
{% codeExample 'rgb', false %}
|
|
@debug rgb(0 51 102); // #036
|
|
@debug rgb(95%, 92.5%, 89.5%); // #f2ece4
|
|
@debug rgb(0 51 102 / 50%); // rgba(0, 51, 102, 0.5)
|
|
@debug rgba(95%, 92.5%, 89.5%, 0.2); // rgba(242, 236, 228, 0.2)
|
|
===
|
|
@debug rgb(0 51 102) // #036
|
|
@debug rgb(95%, 92.5%, 89.5%) // #f2ece4
|
|
@debug rgb(0 51 102 / 50%) // rgba(0, 51, 102, 0.5)
|
|
@debug rgba(95%, 92.5%, 89.5%, 0.2) // rgba(242, 236, 228, 0.2)
|
|
{% endcodeExample %}
|
|
|
|
{{ '---' | markdown }}
|
|
|
|
{% markdown %}
|
|
If `$color` and `$alpha` are passed, this returns `$color` with the given
|
|
`$alpha` channel instead of its original alpha channel.
|
|
{% endmarkdown %}
|
|
|
|
{% codeExample 'color-and-alpha', false %}
|
|
@debug rgb(#f2ece4, 50%); // rgba(242, 236, 228, 0.5);
|
|
@debug rgba(rgba(0, 51, 102, 0.5), 1); // #003366
|
|
===
|
|
@debug rgb(#f2ece4, 50%) // rgba(242, 236, 228, 0.5)
|
|
@debug rgba(rgba(0, 51, 102, 0.5), 1) // #003366
|
|
{% endcodeExample %}
|
|
{% endfunction %}
|