---
title: Built-In Modules
eleventyComputed:
  before_introduction: >
    {% render 'documentation/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 %}
    ---

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