Built-in Modules

This section documents Sass/SCSS as implemented by Dart Sass, the current official and actively maintained compiler — it is not tied to any specific book, build tool, or CSS framework (Bootstrap, Bulma, etc.). Unlike the other reference sections on this site, no single reference book underpins it: the content was generated with the assistance of AI from general knowledge of Dart Sass, and should be verified against the current official documentation at sass-lang.com before relying on it in production. Sass continues to evolve, so behaviour described here may lag the compiler you are actually running.

This section’s bibliography lists the reference material consulted while preparing these pages.

Sass ships a standard library organised into modules with the sass: prefix. Each is loaded with @use like any other module (see Partials & Modules), and its members are reached through a namespace:

@use "sass:math";
@use "sass:color";
@use "sass:map";

.button {
  width: math.div(100%, 3);
  background: color.adjust(#3f51b5, $lightness: -10%);
  border-radius: map.get($radii, md);
}

Built-in modules need no file path and are always available — there is nothing to install. As with any @use, they can be aliased (@use "sass:math" as m;) or loaded unnamespaced (@use "sass:math" as *;), though the namespace is short enough that keeping it is usually clearer.

The modules at a glance

Module Purpose Most commonly used

sass:math

Numeric operations, rounding, units

math.div()

sass:color

Inspect and transform colours

color.adjust()

sass:list

Operate on lists

list.append()

sass:map

Operate on maps

map.get()

sass:string

Quoting, slicing, and building strings

string.quote()

sass:selector

Inspect and manipulate selectors

selector.nest()

sass:meta

Introspection and metaprogramming

meta.type-of()

sass:math

Function Description Example

math.div($a, $b)

Division — the required replacement for /

math.div(100%, 3) → 33.3333333333%

math.percentage($n)

Unitless fraction → percentage

math.percentage(0.25) → 25%

math.round($n)

Nearest whole number

math.round(2.6) → 3

math.ceil($n) / math.floor($n)

Round up / down

math.ceil(2.1) → 3

math.abs($n)

Absolute value

math.abs(-8px) → 8px

math.min($n…​) / math.max($n…​)

Smallest / largest

math.max(1px, 4px) → 4px

math.clamp($min, $n, $max)

Constrain to a range

math.clamp(0, 150, 100) → 100

math.sqrt($n) / math.pow($b, $e)

Square root / exponent

math.pow(2, 10) → 1024

math.hypot($n…​)

Euclidean length

math.hypot(3, 4) → 5

math.is-unitless($n)

Whether $n has no unit

math.is-unitless(5) → true

math.compatible($a, $b)

Whether units can be combined

math.compatible(1in, 1px) → true

math.unit($n)

The unit as a string

math.unit(8px) → "px"

Constants: math.$pi, math.$e. Trigonometric functions (math.sin(), math.cos(), math.atan2(), …​) take and return angle units.

@use "sass:math";

@function rem($px, $base: 16px) {
  @return math.div($px, $base) * 1rem;
}

.col-4 { width: math.percentage(math.div(4, 12)); }   // 33.3333333333%

Note that math.min()/math.max() are distinct from CSS’s own min()/max(), which the browser evaluates at runtime. Sass will pass through an unquoted min(…​)/max(…​) containing units it cannot reconcile, but being explicit with the math. namespace avoids the ambiguity entirely.

sass:color

Function Description Example

color.adjust($c, $args…​)

Add to a channel ($lightness, $alpha, $hue, …​)

color.adjust(#3f51b5, $lightness: -10%)

color.scale($c, $args…​)

Scale a channel proportionally toward its limit

color.scale(#3f51b5, $lightness: 40%)

color.change($c, $args…​)

Set a channel to an absolute value

color.change(#3f51b5, $alpha: 0.5)

color.mix($c1, $c2, $weight)

Blend two colours

color.mix(red, blue, 25%)

color.invert($c)

Inverse colour

color.invert(#3f51b5)

color.grayscale($c)

Desaturate fully

color.grayscale(#3f51b5)

color.complement($c)

Hue rotated 180°

color.complement(#3f51b5)

color.channel($c, $ch, $space:)

Read one channel (from the given colour space)

color.channel(#3f51b5, "lightness", $space: hsl)

The three transformation functions differ in a way worth understanding:

  • color.adjust() adds a fixed amount: $lightness: -10% subtracts 10 percentage points.

  • color.scale() moves a fraction of the remaining distance to the limit: $lightness: 40% closes 40% of the gap to white. This degrades gracefully and never overshoots, which makes it the better choice for deriving a palette.

  • color.change() sets the channel outright, ignoring its current value.

@use "sass:color";

$brand: #3f51b5;

.button {
  background: $brand;
  &:hover  { background: color.adjust($brand, $lightness: -8%); }
  &:disabled { background: color.change($brand, $alpha: 0.4); }
}

.button--subtle { background: color.scale($brand, $lightness: 70%); }

The older global colour functions — lighten(), darken(), saturate(), desaturate(), opacify(), transparentize(), fade-out() — are deprecated in favour of color.adjust()/color.scale(). They are also easy to misuse: darken($c, 20%) subtracts 20 points of lightness regardless of the starting colour, so it turns a near-black into pure black rather than something merely darker. Prefer color.scale().

sass:list

Function Description Example

list.nth($l, $n)

Element at 1-based index $n

list.nth(a b c, 2) → b

list.length($l)

Element count

list.length(a b c) → 3

list.index($l, $v)

Index of $v, else null

list.index(a b c, c) → 3

list.append($l, $v)

New list with $v appended

list.append(a b, c) → a b c

list.join($l1, $l2)

Concatenate

list.join(a b, c) → a b c

list.zip($l…​)

Combine element-wise

list.zip(1px 2px, red blue)

list.separator($l)

comma / space / slash

list.separatora, b → comma

list.slash($v…​)

Slash-separated list

list.slash(16px, 1.5) → 16px/1.5

See Lists & Maps for worked examples and the 1-indexing caveat.

sass:map

Function Description Example

map.get($m, $key…​)

Value for a key (or nested key path), else null

map.get($bp, md) → 768px

map.set($m, $key…​, $v)

New map with the key set

map.set($bp, xxl, 1400px)

map.merge($m1, $m2)

Combine; $m2 wins conflicts

map.merge($defaults, $user)

map.remove($m, $keys…​)

New map without those keys

map.remove($bp, sm)

map.has-key($m, $key…​)

Key presence

map.has-key($bp, md) → true

map.keys($m)

Comma list of keys

map.keys($bp)

map.values($m)

Comma list of values

map.values($bp)

sass:string

Function Description Example

string.quote($s)

Add quotes

string.quote(foo) → "foo"

string.unquote($s)

Remove quotes

string.unquote("foo") → foo

string.length($s)

Character count

string.length("abc") → 3

string.index($s, $sub)

1-based position of $sub, else null

string.index("abcd", "c") → 3

string.slice($s, $start, $end)

Substring (1-based, inclusive)

string.slice("abcd", 2, 3) → "bc"

string.insert($s, $ins, $i)

Insert at index

string.insert("abcd", "X", 2) → "aXbcd"

string.to-upper-case($s)

Uppercase

string.to-upper-case("ab") → "AB"

string.to-lower-case($s)

Lowercase

string.to-lower-case("AB") → "ab"

string.unique-id()

A random unique unquoted string

uabc123

string.unquote() matters when building a value that must not carry quotes in the output:

@use "sass:string";

$family: "Inter";
.a { font-family: string.unquote($family), sans-serif; }

Note that strings are also 1-indexed, and `string.slice()’s end index is inclusive — both differ from most other languages.

sass:selector

Rarely needed, but useful when writing a mixin that must reason about where it was included.

Function Description

selector.nest($selectors…​)

Combine selectors as if nested

selector.append($selectors…​)

Concatenate without a combinator (like &__x)

selector.unify($s1, $s2)

A selector matching both, or null

selector.is-superselector($a, $b)

Whether $a matches everything $b does

selector.parse($s)

A selector string as a list structure

selector.replace($s, $orig, $new)

Substitute within a selector

sass:meta

Function Description Example

meta.type-of($v)

Type name

meta.type-of(8px) → number

meta.inspect($v)

Debug string of any value (maps included)

meta.inspect($map)

meta.keywords($args)

Named args of a variadic mixin/function, as a map

see Mixins

meta.variable-exists($name)

Whether a variable is defined

meta.variable-exists(primary)

meta.mixin-exists($name)

Whether a mixin is defined

meta.mixin-exists(button)

meta.function-exists($name)

Whether a function is defined

meta.function-exists(rem)

meta.get-function($name)

A first-class function reference

meta.get-function("rem")

meta.call($fn, $args…​)

Invoke a function reference

meta.call($fn, 24px)

meta.load-css($url, $with)

Load a module’s CSS dynamically

meta.load-css("theme")

meta.inspect() is the practical everyday one — it is the only way to print a map or list legibly:

@use "sass:meta";
@debug meta.inspect($breakpoints);   // (sm: 576px, md: 768px, lg: 992px)

Global functions are deprecated

Before the module system, every built-in was a single global function: nth(), map-get(), darken(), str-length(), type-of(), and so on. These still work for backwards compatibility but are deprecated; new code should use the namespaced module forms.

Global (deprecated) Module form

percentage($n)

math.percentage($n)

round($n)

math.round($n)

lighten($c, 10%) / darken($c, 10%)

color.adjust($c, $lightness: ±10%) (or color.scale())

transparentize($c, 0.5)

color.adjust($c, $alpha: -0.5)

nth($l, $n)

list.nth($l, $n)

length($l)

list.length($l)

map-get($m, $k)

map.get($m, $k)

map-merge($m1, $m2)

map.merge($m1, $m2)

str-length($s)

string.length($s)

type-of($v)

meta.type-of($v)

A handful of functions remain global because they are not part of any module:

  • rgb(), rgba(), hsl(), hsla() — not deprecated; these mirror the CSS functions of the same names.

  • if($condition, $if-true, $if-false) — lazily evaluates only the branch it returns, but is itself now deprecated in favor of the modern CSS if() syntax (if(sass($condition): $if-true; else: $if-false)); see the deprecation notice.

The sass-migrator tool can convert global calls to module calls automatically:

sass-migrator module --migrate-deps scss/main.scss