Skip to main content

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:

OptionTypeDefaultMeaning
propertyRequired—CSS property name, or a list of them (e.g. margin-right margin-left).
valuesRequired—List or map. A map gives key: value pairs; a list uses the value as its own suffix.
classOptionalproperty nameClass prefix. null means no prefix (used by .shadow).
css-varOptionalfalseEmit a CSS variable instead of a declaration.
css-variable-nameOptionalclassName for that variable.
local-varsOptionalnullExtra variables set on the rule (how .bg-* gets --bs-bg-opacity).
stateOptionalnullPseudo-classes to generate variants for, e.g. hover focus.
responsiveOptionalfalseAlso emit -sm, -md, -lg, -xl, -xxl infixes.
rfsOptionalfalseRun values through RFS fluid rescaling.
printOptionalfalseAlso emit a -print variant inside @media print.
rtlOptionaltrueKeep 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,
  ),
),
Slide 1
Slide 2
Slide 3
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, …