sass-site/source/documentation/modules/index.md

title	eleventyComputed	introduction
Built-In Modules	before_introduction {% render 'doc_snippets/built-in-module-status' %}	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.

{% 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%) {% endcodeExample %}

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.

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' %} {% 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 %}

Returns a color with the given hue, saturation, and lightness and the given alpha channel.

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).

{% funFact %} 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

{% 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)' %} 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.

{% 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 %}

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).

{% funFact %} 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

{% 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 %}

---

If $color and $alpha are passed, this returns $color with the given $alpha channel instead of its original alpha channel.

{% 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 %}