Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 39 ยท Modules and Architecture

Sass Built-in Modules (math, string, list, map, color, meta)

A tour of Sass's built-in modules: sass:math, sass:string, sass:list, sass:map, sass:color, sass:selector and sass:meta, with live examples and the old global functions mapped to them.

Sass ships with a library of functions, split into modules you load with @use "sass:name". You have probably met some of them as global functions (map-get, lighten, percentage). The global names still work for now, but they are deprecated and will be removed in Dart Sass 3.0, so new code should use the modules. This lesson is a guided tour with the functions you will use every week.

The playgrounds below print values into CSS custom properties so you can see exactly what each function returns.

sass:math

SCSS
@use "sass:math";

.demo {
  --div: #{math.div(10px, 4)};          // 2.5px
  --round: #{math.round(2.5)};          // 3
  --ceil: #{math.ceil(2.1)};            // 3
  --floor: #{math.floor(2.9)};          // 2
  --pct: #{math.percentage(math.div(1, 3))};  // 33.3333333333%
  --pow: #{math.pow(2, 10)};            // 1024
  --clamp: #{math.clamp(10px, 50px, 30px)};   // 30px
}

The big change from old Sass: the / operator is no longer division. Use math.div(). A plain slash is now just a separator (as in font: 12px/1.5 or grid-area: 1 / 3). Other useful members: math.abs, math.min, math.max, math.sqrt, math.hypot, math.log, trig functions (math.sin(45deg)), the constants math.$pi and math.$e, and the unit helpers math.unit(12px) (returns "px"), math.is-unitless(3) and math.compatible(1px, 1em).

sass:math in practice

sass:string

SCSS
@use "sass:string";

string.to-upper-case("sass");        // "SASS"
string.length("hello");              // 5
string.slice("abcdef", 2, 4);        // "bcd"  (1-based, inclusive)
string.index("a-b-c", "-");          // 2
string.insert("ac", "b", 2);         // "abc"
string.quote(hello);                 // "hello"
string.unquote("sans-serif");        // sans-serif
string.unique-id();                  // e.g. u1a2b3c, a valid unique identifier

Remember that Sass strings are 1-indexed, and negative indices count from the end. unquote is how you emit a value that must not carry quotes, and quote does the opposite.

sass:list

Lists are comma, space or slash separated; a single value counts as a list of one.

SCSS
@use "sass:list";

$sizes: 4px 8px 16px;
list.length($sizes);               // 3
list.nth($sizes, 2);               // 8px
list.nth($sizes, -1);              // 16px
list.append($sizes, 32px);         // 4px 8px 16px 32px
list.join((a, b), (c, d), comma);  // a, b, c, d
list.index($sizes, 16px);          // 3
list.separator($sizes);            // space
list.set-nth($sizes, 1, 2px);      // 2px 8px 16px
list.zip(1 2 3, a b c);            // 1 a, 2 b, 3 c
list.slash(12px, 1.5);             // a slash-separated list: 12px / 1.5

Lists are immutable: append returns a new list, so you must assign it ($list: list.append($list, $x)). To check a list's contents in a loop, see the control-flow chapter.

sass:map

SCSS
@use "sass:map";

$colors: (primary: #4f46e5, danger: #dc2626);

map.get($colors, primary);                      // #4f46e5
map.has-key($colors, warning);                  // false
map.merge($colors, (warning: #f59e0b));         // adds a key
map.remove($colors, danger);                    // removes a key
map.keys($colors);                              // primary, danger
map.values($colors);                            // #4f46e5, #dc2626

Nested maps have helpers: map.get($theme, "colors", "primary") walks down a path, map.set($theme, "colors", "primary", red) creates a new map with a nested value changed, map.deep-merge merges recursively, and map.deep-remove removes a nested key. Like lists, maps are immutable.

sass:color

Modern Sass colors have a unified API around color.adjust, color.scale and color.change:

SCSS
@use "sass:color";

$brand: #4f46e5;
color.adjust($brand, $lightness: -10%);    // darker by 10 points
color.scale($brand, $lightness: -30%);     // moves 30% of the way to black
color.change($brand, $alpha: 0.5);         // sets alpha
color.mix(white, $brand, 20%);             // 20% white, 80% brand
color.channel($brand, "red", $space: rgb); // 79

The difference matters: adjust adds or subtracts a fixed amount; scale moves a percentage of the remaining distance, so it never overshoots; change replaces a channel. The old lighten(), darken(), saturate(), transparentize(), fade-in() and friends are deprecated; replace darken($c, 10%) with color.adjust($c, $lightness: -10%). Recent Sass versions also understand modern color spaces (oklch, display-p3) and accept $space arguments, so check your compiler's release notes when you need them.

Color helpers and maps

sass:selector

Selector functions are for library authors who build selectors programmatically:

SCSS
@use "sass:selector";

selector.nest(".card", ".title");            // .card .title
selector.append(".button", ".-primary");     // .button.-primary
selector.unify(".a", "a");                   // a.a
selector.is-superselector("a", "a.active");  // true
selector.replace(".a .b", ".b", ".c");       // .a .c

sass:meta

sass:meta is reflection: ask Sass about values, and call functions by name.

SCSS
@use "sass:meta";

meta.type-of(12px);            // number
meta.type-of(#fff);            // color
meta.inspect((a: 1));          // (a: 1)
meta.variable-exists(brand);   // checks the current scope
meta.function-exists("rem");
meta.mixin-exists("card");
meta.call(meta.get-function("rem"), 24);   // call a function by value
meta.keywords($args);                       // from a rest argument

meta.get-function returns a function value you can store in a variable or pass to another function, which is how Sass supports higher-order helpers in the functions chapter. meta.load-css was covered in module configuration.

Types and reflection

Global functions and their module replacements

Old global Use instead
map-get, map-merge, map-has-key map.get, map.merge, map.has-key
nth, append, join, length list.nth, list.append, list.join, list.length
percentage, round, floor, abs math.percentage, math.round, math.floor, math.abs
lighten, darken color.adjust($c, $lightness: ยฑn%)
transparentize, rgba($c, a) color.change($c, $alpha: a)
unquote, to-upper-case, str-length string.unquote, string.to-upper-case, string.length
type-of, inspect, call, get-function the same names in meta
a / b division math.div(a, b)

Functions that exist in CSS itself (rgb(), hsl(), min(), max(), clamp(), calc(), var()) are not Sass modules; they pass through to the browser or are evaluated when all arguments are compatible Sass numbers. Plain CSS min() and max() with mixed units are left for the browser.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. How do you divide two numbers in modern Sass?

    The slash is no longer division; math.div replaces it.
  2. 2. What is the difference between color.adjust and color.scale?

    Scaling is relative to how far the channel is from its limit, so it cannot overshoot.
  3. 3. Why must you write $list: list.append($list, $x)?

    Sass values are immutable; functions return new values rather than changing the old one.
  4. 4. Which module do you load for meta.type-of?

    All built-in modules use the sass: prefix and the module name.
  5. 5. What replaces map-get($m, k) in new code?

    The module versions share the old names without the map- prefix.

Summary

  • Load built-ins with @use "sass:math", "sass:string", "sass:list", "sass:map", "sass:color", "sass:selector", "sass:meta".
  • Use math.div instead of / for division.
  • Lists and maps are immutable; functions return new values.
  • Prefer color.adjust, color.scale, color.change and color.mix over the old lighten/darken family.
  • sass:meta offers type checks, existence checks, get-function/call, and load-css.

Next: Project Architecture and the 7-1 Pattern