Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 39 ยท Mixins and Functions

Sass Math, String and List Functions

A practical tour of the sass:math, sass:string and sass:list modules: rounding, min and max, pow, slicing and splitting strings, and nth, append, join and zip.

Sass ships with a standard library of functions, organized into modules you load with @use. You do not install anything; the names start with sass:. This lesson covers the three you will use most often after the color module: sass:math for numbers, sass:string for text and sass:list for sequences. (Maps and the sass:map and sass:meta modules come next, and Built-in modules gives the complete catalog.)

SCSS
@use "sass:math";
@use "sass:string";
@use "sass:list";

Functions are then called with the module name as a prefix, such as math.round(4.6).

sass:math

Function Result for example
math.round(4.6) 5
math.ceil(4.1) 5
math.floor(4.9) 4
math.abs(-3px) 3px
math.min(4px, 2px, 9px) 2px
math.max(4px, 2px, 9px) 9px
math.clamp(10px, 50px, 30px) 30px (min, preferred, max)
math.div(7, 2) 3.5
math.percentage(math.div(1, 3)) 33.3333333333%
math.pow(2, 8) 256
math.sqrt(81) 9
math.unit(12px) "px"
math.is-unitless(5) true
math.compatible(1in, 2cm) true

There are also logarithms, trigonometry (math.sin, math.cos, math.atan2, with angle units), math.hypot, and constants such as math.$pi, math.$e. math.random() gives a different number every compile; avoid it for output you want to keep stable.

Careful with min() and max(). CSS also has min() and max() functions that the browser evaluates. The Sass ones from sass:math calculate at compile time and require compatible units. A plain min(100%, 40rem) with no module prefix is passed through to CSS for the browser, which is usually what you want for fluid layouts.

Math functions

A fluid-type helper

Combining math with a function gives you a reusable ratio. A modular scale multiplies a base size by a ratio raised to a step:

SCSS
@use "sass:math";

@function scale($step, $base: 1rem, $ratio: 1.25) {
  @return $base * math.pow($ratio, $step);
}

h3 { font-size: scale(1); }   // 1.25rem
h2 { font-size: scale(2); }   // 1.5625rem
h1 { font-size: scale(3); }   // 1.953125rem

sass:string

Strings are indexed from 1, not 0, and negative indexes count from the end.

Function Result for example
string.length("hello") 5
string.to-upper-case("abc") "ABC"
string.to-lower-case("ABC") "abc"
string.slice("abcdef", 2, 4) "bcd"
string.index("hello", "ll") 3
string.insert("abc", "X", 2) "aXbc"
string.split("a,b,c", ",") ["a", "b", "c"] (a bracketed list)
string.unquote("sans-serif") sans-serif (no quotes)
string.quote(Inter) "Inter"
string.unique-id() a unique identifier

The most useful in everyday work are unquote (to emit a raw value such as a keyword or a selector) and quote/slice when you build class names. Use them together with interpolation.

sass:list

A list is an ordered series of values separated by spaces or commas. A single value is a list of one. Sass lists are indexed from 1 and are immutable: functions return a new list.

Function Result for example
list.length(1 2 3) 3
list.nth(a b c, 2) b
list.nth(a b c, -1) c
list.append(1 2, 3) 1 2 3
list.join((1 2), (3 4)) 1 2 3 4
list.index(a b c, c) 3
list.set-nth(a b c, 2, x) a x c
list.separator(a, b) comma
list.zip(1 2 3, a b c) 1 a, 2 b, 3 c
list.slash(1, 2) 1 / 2

You can also get a comma or space separator when you build a list: list.append($l, $item, comma).

String and list functions

Putting them together

A mixin that writes a full spacing scale class set using list functions and math:

SCSS
@use "sass:list";
@use "sass:math";

$steps: 1 2 3 4 6 8;

@for $i from 1 through list.length($steps) {
  $n: list.nth($steps, $i);
  .gap-#{$n} { gap: math.div($n * 4, 16) * 1rem; }
}

This prints .gap-1 { gap: 0.25rem; } and so on. The @for loop is explained in the next chapter's loops lesson.

When you forget a function's name, remember the three groups: math. for numbers, string. for text, list. for sequences, map. for key/value pairs, meta. for inspecting types, and selector. for building selectors.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does list.nth(a b c, 2) return?

    Sass lists are 1-indexed, so the second item is b.
  2. 2. What does math.clamp(10px, 50px, 30px) return?

    clamp(min, value, max) limits the value to the range, so 50px becomes 30px.
  3. 3. How do you remove the quotes from a string at compile time?

    string.unquote returns the same text as an unquoted string.
  4. 4. Are Sass lists mutable?

    Sass values are immutable. Assign the result of the function to a variable to keep it.

Summary

  • Load modules with @use "sass:math", "sass:string", "sass:list" and call functions with the module prefix.
  • math handles rounding, min/max/clamp, powers, roots, unit checks and trig; math.div replaces /.
  • string offers length, slice, case conversion, index, insert, split and quote/unquote.
  • list offers length, nth, append, join, index, set-nth, zip and separator; indexes start at 1.
  • All values are immutable: functions return new values.

Next: If, else and conditions