String, List & Map Modules
Manipulate strings, lists, and maps with their built-in modules.
Syntax
@use 'sass:string'; @use 'sass:list'; @use 'sass:map';Three more built-in modules cover the other data types.
sass:string
string.to-upper-case(),string.length(),string.slice(),string.index().
sass:list
list.length(),list.nth(),list.append(),list.join(),list.index().
sass:map
map.get(),map.has-key(),map.keys(),map.values(),map.merge(),map.set().
These modules turn Sass into a small data-processing language for generating CSS.
Example
@use 'sass:map';
@use 'sass:string';
$z-index: ('modal': 400, 'tooltip': 500);
.modal { z-index: map.get($z-index, 'modal'); }
.tooltip { z-index: map.get($z-index, 'tooltip'); }
.tag::before {
content: string.to-upper-case('new'); // "NEW"
}When to use it
- A developer uses sass:string's index() and slice() to extract file-path segments from a variable when building dynamic asset URLs.
- A mixin library uses sass:list's join() to merge two box-shadow lists so consumers can add shadows to an existing stack without overwriting it.
- A design token system uses sass:map's deep-merge() to let project themes override individual nested token values without replacing entire sub-maps.
More examples
String operations with sass:string
Demonstrates three sass:string functions — to-upper-case, length, and slice — applied to a design token name variable.
@use 'sass:string';
$name: 'primary-button';
.debug {
// 'PRIMARY-BUTTON'
content: string.to-upper-case($name);
// Length: 14
length: string.length($name);
// Slice first word: 'primary'
word: string.slice($name, 1, 7);
}List operations with sass:list
Uses list.join() to merge a base shadow and an extra elevation shadow into a combined comma-separated box-shadow value.
@use 'sass:list';
$base-shadows: 0 1px 3px rgba(0,0,0,.1);
$extra: 0 8px 16px rgba(0,0,0,.15);
$combined: list.join($base-shadows, $extra, $separator: comma);
.card-elevated {
box-shadow: $combined;
}Map deep-merge with sass:map
Uses map.deep-merge() to layer override values onto defaults, preserving all keys not explicitly overridden in nested maps.
@use 'sass:map';
$defaults: (color: (primary: blue, secondary: gray), space: (base: 1rem));
$overrides: (color: (primary: #e74c3c));
$theme: map.deep-merge($defaults, $overrides);
// Result: (color: (primary: #e74c3c, secondary: gray), space: (base: 1rem))
.btn { background: map.get(map.get($theme, color), primary); }
Discussion