Utilities
API
How the $utilities map generates every utility class, and the five entries this theme adds to it.
How it works
Every utility class — .mt-4, .text-gold, .d-md-flex — is generated
from one Sass map, $utilities. Each key describes a property, the class prefix and a map of
values; a loop in utilities/_api.scss turns that into CSS, with responsive and print
variants where asked for.
rb-bootstrap loads Bootstrap's map, then scss/_utilities.scss merges five entries into it,
then the API runs last in scss/rb-bootstrap.scss so utilities win over components.
That is also where you plug in your own.
@import "../node_modules/bootstrap/scss/utilities"; // Bootstrap's $utilities
@import "utilities"; // theme additions (map-merge)
// … layout, components, brand …
@import "../node_modules/bootstrap/scss/utilities/api"; // generate, last
Anatomy of an entry
The key is a label only. The options inside it do the work:
| Option | Type | Default | Meaning |
|---|---|---|---|
property | Required | — | CSS property name, or a list of them (e.g. margin-right margin-left). |
values | Required | — | List or map. A map gives key: value pairs; a list uses the value as its own suffix. |
class | Optional | property name | Class prefix. null means no prefix (used by .shadow). |
css-var | Optional | false | Emit a CSS variable instead of a declaration. |
css-variable-name | Optional | class | Name for that variable. |
local-vars | Optional | null | Extra variables set on the rule (how .bg-* gets --bs-bg-opacity). |
state | Optional | null | Pseudo-classes to generate variants for, e.g. hover focus. |
responsive | Optional | false | Also emit -sm, -md, -lg, -xl, -xxl infixes. |
rfs | Optional | false | Run values through RFS fluid rescaling. |
print | Optional | false | Also emit a -print variant inside @media print. |
rtl | Optional | true | Keep the utility in RTL builds. |
A minimal example, and what it produces:
$utilities: (
"opacity": (
property: opacity,
values: (
0: 0,
25: .25,
50: .5,
75: .75,
100: 1,
)
)
);
.opacity-0 { opacity: 0 !important; }
.opacity-25 { opacity: 0.25 !important; }
.opacity-50 { opacity: 0.5 !important; }
.opacity-75 { opacity: 0.75 !important; }
.opacity-100 { opacity: 1 !important; }
What this theme adds
scss/_utilities.scss is one map-merge. Two entries extend Bootstrap's own
(font-family, font-weight) by merging into the existing values; three are new.
Every class below is in dist/rb-bootstrap.css.
Display font — .font-display
Joins .font-monospace. Puts Big Shoulders Display on anything; see Typography for why h4–h6 do not get it by default.
"font-family": map-merge(
map-get($utilities, "font-family"),
(
values: (
monospace: var(--#{$prefix}font-monospace),
display: var(--#{$prefix}font-display),
),
)
),
Tonight: the main event
HTML
<p class="font-display fs-2 text-uppercase mb-0">Tonight: the main event</p>Weight — .fw-black
Adds black: 800 to the fw values. Note the theme also sets
$font-weight-bolder: 800, so .fw-bolder and .fw-black currently
compile to the same weight; .fw-black is the explicit one for marquee type.
"font-weight": map-merge(
map-get($utilities, "font-weight"),
(
values: map-merge(
map-get(map-get($utilities, "font-weight"), "values"),
("black": 800)
),
)
),
Sold out
HTML
<p class="font-display fw-black fs-1 text-uppercase mb-0">Sold out</p>Letter spacing — .ls-*
Three stops. display is the tracking the brand layer puts on h1–h3; wide is for small caps labels.
"letter-spacing": (
property: letter-spacing,
class: ls,
values: (
tight: 0,
display: 0.01em,
wide: 0.08em,
),
),
Tight — letter-spacing: 0
Display — 0.01em
Wide — 0.08em, for eyebrow labels
HTML
<p class="ls-tight">Tight — letter-spacing: 0</p>
<p class="ls-display font-display fs-3 text-uppercase">Display — 0.01em</p>
<p class="ls-wide text-uppercase small fw-bold mb-0">Wide — 0.08em, for eyebrow labels</p>Transition — .transition-*
Applies the motion tokens: base is all 200ms cubic-bezier(.2, 0, 0, 1),
fade is opacity 120ms linear. Both variables become none under
prefers-reduced-motion, so the utilities respect it for free.
"transition": (
property: transition,
class: transition,
values: (
base: var(--#{$prefix}transition-base),
fade: var(--#{$prefix}transition-fade),
none: none,
),
),
HTML
<a href="#!" class="btn btn-outline-primary transition-base">Hover me — base</a>
<a href="#!" class="btn btn-outline-primary transition-none">Hover me — none</a>Scroll snap — .snap-*
scroll-snap-type on a scroll container. The carousel
is built on this; the utility lets you make any overflow box snap.
"scroll-snap": (
property: scroll-snap-type,
class: snap,
values: (
x: x mandatory,
y: y mandatory,
both: both mandatory,
none: none,
),
),
HTML
<div class="d-flex overflow-auto snap-x gap-3 pb-2">
<div class="flex-shrink-0 w-75 ratio ratio-21x9 text-bg-navy" style="scroll-snap-align: start"><div class="d-flex align-items-center justify-content-center">Slide 1</div></div>
<div class="flex-shrink-0 w-75 ratio ratio-21x9 text-bg-gold" style="scroll-snap-align: start"><div class="d-flex align-items-center justify-content-center">Slide 2</div></div>
<div class="flex-shrink-0 w-75 ratio ratio-21x9 text-bg-cream" style="scroll-snap-align: start"><div class="d-flex align-items-center justify-content-center">Slide 3</div></div>
</div>Children still need scroll-snap-align; there is no utility for it.
Adding utilities
Put your own map-merge after the theme's utilities import and before the API. New keys are
appended; a key that already exists is replaced wholesale, so extend rather than overwrite when you only
want to add values.
@import "@ropebreak/bootstrap/scss/palette";
// … functions, variables, maps, mixins, utilities as in scss/rb-bootstrap.scss …
@import "@ropebreak/bootstrap/scss/utilities";
$utilities: map-merge(
$utilities,
(
"cursor": (
property: cursor,
class: cursor,
responsive: true,
values: auto pointer grab,
)
)
);
@import "bootstrap/scss/utilities/api";
Modifying utilities
Use map-get to pull an entry out, change one option, and merge it back. Here .w-* gains a responsive variant and a 10 step:
$utilities: map-merge(
$utilities,
(
"width": map-merge(
map-get($utilities, "width"),
(
responsive: true,
values: map-merge(
map-get(map-get($utilities, "width"), "values"),
(10: 10%)
),
)
),
)
);
Removing utilities
Set the key to null or use map-remove. Both skip generation entirely.
// Drop float and user-select
$utilities: map-remove($utilities, "float", "user-select");
// Same thing, inline
$utilities: map-merge(
$utilities,
("float": null)
);
To remove just one value, merge a values map that omits it, or set that value's key to
null.
Responsive, state and print
responsive: true emits the class once per breakpoint infix. For the theme that is sm md lg xl xxl:
.ls-wide { letter-spacing: 0.08em !important; }
/* with responsive: true you would also get */
@media (min-width: 768px) { .ls-md-wide { letter-spacing: 0.08em !important; } }
state appends a pseudo-class suffix. This is how .link-opacity-50-hover exists:
"link-opacity": (
css-var: true,
class: link-opacity,
state: hover,
values: (10: .1, 25: .25, 50: .5, 75: .75, 100: 1)
),
print: true adds a -print variant inside @media print, as the display utility does (.d-print-none).
Importance
Every utility ends in !important because $enable-important-utilities is
true. Set it to false before importing to drop it — then source order decides,
and a component rule later in the sheet can override a utility.
$enable-important-utilities: false;
Other options that shape the output live in Options:
$enable-negative-margins (on here, giving .mt-n1 … .mt-n8) and
$enable-cssgrid (on, see CSS grid).
Using the API
The generator is also callable directly. generate-utility($utility, $infix) emits one entry;
wrap it in your own media query to build a variant Bootstrap does not offer, such as a
prefers-reduced-motion infix.
@media (prefers-reduced-motion: reduce) {
@include generate-utility(map-get($utilities, "transition"), "-reduced");
}
// → .transition-reduced-none, .transition-reduced-base, …