mirror of
https://github.com/danog/sass-site.git
synced 2024-12-03 09:57:58 +01:00
279 lines
10 KiB
Plaintext
279 lines
10 KiB
Plaintext
---
|
|
title: Built-In Modules
|
|
introduction: >
|
|
Sass provides many built-in modules which contain useful functions (and the
|
|
occasional mixin). These modules can be loaded with the
|
|
[`@use` rule](at-rules/use) like any user-defined stylesheet, and their
|
|
functions can be called [like any other module
|
|
member](at-rules/use#loading-members). All built-in module URLs begin with
|
|
`sass:` to indicate that they're part of Sass itself.
|
|
overview: true
|
|
---
|
|
|
|
<% content_for :before_introduction do %>
|
|
<%= partial 'snippets/built-in-module-status' %>
|
|
<% end %>
|
|
|
|
<% heads_up do %>
|
|
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
|
|
<% end %>
|
|
|
|
<% example do %>
|
|
@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;
|
|
}
|
|
<% end %>
|
|
|
|
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]: modules/math
|
|
[numbers]: values/numbers
|
|
[`sass:string` module]: modules/string
|
|
[strings]: values/strings
|
|
[`sass:color` module]: modules/color
|
|
[colors]: values/colors
|
|
[`sass:list` module]: modules/list
|
|
[lists]: values/lists
|
|
[`sass:map` module]: modules/map
|
|
[map]: values/maps
|
|
[`sass:selector` module]: modules/selector
|
|
[`sass:meta` module]: modules/meta
|
|
|
|
## Global Functions
|
|
|
|
<% 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' do %>
|
|
<% impl_status dart: '1.15.0', libsass: false, ruby: false, feature: "Level 4 Syntax" do %>
|
|
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.
|
|
<% end %>
|
|
|
|
<% impl_status dart: true, libsass: false, ruby: '3.7.0', feature: "Percent Alpha" do %>
|
|
LibSass and older versions of Ruby Sass don't support alpha values specified as
|
|
percentages.
|
|
<% end %>
|
|
|
|
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).
|
|
|
|
[unitless]: values/numbers#units
|
|
|
|
<% fun_fact do %>
|
|
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]: syntax/special-functions
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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%)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% heads_up do %>
|
|
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]: operators/numeric#slash-separated-values
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% function "if($condition, $if-true, $if-false)" do %>
|
|
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]: at-rules/control/if#truthiness-and-falsiness
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|
|
|
|
|
|
<% 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' do %>
|
|
<% impl_status dart: '1.15.0', libsass: false, ruby: false, feature: "Level 4 Syntax" do %>
|
|
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.
|
|
<% end %>
|
|
|
|
<% impl_status dart: true, libsass: false, ruby: '3.7.0', feature: "Percent Alpha" do %>
|
|
LibSass and older versions of Ruby Sass don't support alpha values specified
|
|
as percentages.
|
|
<% end %>
|
|
|
|
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]: values/numbers#units
|
|
|
|
<% fun_fact do %>
|
|
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]: syntax/special-functions
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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)
|
|
<% end %>
|
|
<% end %>
|
|
|
|
<% heads_up do %>
|
|
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]: operators/numeric#slash-separated-values
|
|
<% end %>
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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)
|
|
<% end %>
|
|
|
|
---
|
|
|
|
If `$color` and `$alpha` are passed, this returns `$color` with the given
|
|
`$alpha` channel instead of its original alpha channel.
|
|
|
|
<% example(autogen_css: false) do %>
|
|
@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
|
|
<% end %>
|
|
<% end %>
|