W3cubDocs

/Sass

Built-In Modules

Compatibility:
Dart Sass
since 1.23.0
LibSass
Ruby Sass

Only Dart Sass currently supports loading built-in modules with @use. Users of other implementations must call functions using their global names instead.

Sass provides many built-in modules which contain useful functions (and the occasional mixin). These modules can be loaded with the @use rule like any user-defined stylesheet, and their functions can be called like any other module member. All built-in module URLs begin with sass: to indicate that they're part of Sass itself.

⚠️ Heads up!

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.

@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;
}

Sass provides the following built-in modules:

Global Functions

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) //=> color
Compatibility (Level 4 Syntax):
Dart Sass
since 1.15.0
LibSass
Ruby Sass

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.

Compatibility (Percent Alpha):
Dart Sass
LibSass
Ruby Sass
since 3.7.0

LibSass and older versions of Ruby Sass don’t support alpha values specified as percentages.

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

💡 Fun fact:

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.

@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%)

⚠️ Heads up!

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.

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

@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
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) //=> color
Compatibility (Level 4 Syntax):
Dart Sass
since 1.15.0
LibSass
Ruby Sass

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.

Compatibility (Percent Alpha):
Dart Sass
LibSass
Ruby Sass
since 3.7.0

LibSass and older versions of Ruby Sass don’t support alpha values specified as percentages.

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

💡 Fun fact:

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.

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

⚠️ Heads up!

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.

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

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

@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

© 2006–2022 the Sass team, and numerous contributors
Licensed under the MIT License.
https://sass-lang.com/documentation/modules