Skip to content
Tutorials Center
My learning

Topics

Lesson 23 of 58 ยท Utilities

The Utility API

See how Bootstrap generates utility classes from a Sass map, how to add your own utilities, and weigh the strengths and limits of the utility-first approach.

You have now used dozens of utility classes: mt-3, d-flex, text-center, shadow-sm. It can look as if someone wrote each of them by hand. They did not. Almost every utility in Bootstrap is generated from a single Sass data structure called the Utility API. Understanding it explains why the classes are so consistent (every one has responsive versions, names follow one pattern) and shows you how to add your own.

This lesson is mostly conceptual. Compiling Sass needs a build step that the live editor on this site does not have, so the Sass is shown as read-only code, and the TryIts demonstrate the resulting CSS. The practical side of Sass comes in Customizing with Sass.

From map to class

Inside Bootstrap's source, a Sass map named $utilities describes every utility group. Each entry says: which CSS property to set, what the class name starts with, and which values are allowed. A tiny entry looks like this:

SCSS
$utilities: (
  "opacity": (
    property: opacity,
    values: (
      0: 0,
      25: .25,
      50: .5,
      75: .75,
      100: 1,
    )
  )
);

Bootstrap loops over the map and prints one rule per value. For the entry above it produces .opacity-0, .opacity-25, .opacity-50, .opacity-75 and .opacity-100. The class name is the map key (opacity) joined to the value key with a hyphen. If you change the map, the CSS changes with it.

flowchart LR
  M["$utilities map<br/>(Sass)"] --> G["Utility generator<br/>loops over keys and values"]
  G --> C["Compiled CSS<br/>.opacity-25 { opacity: .25 }"]
  C --> H["Your HTML<br/>class='opacity-25'"]

One map entry becomes many classes: the generator turns each key and value into a CSS rule.

The options of a utility

Each map entry accepts a small set of options. These are the ones you will meet most:

Option What it does
property The CSS property to set (a single name, or a list for several).
class The class prefix. If omitted, the property name is used (so opacity becomes .opacity-*).
values A map of value names to CSS values, or a plain list.
responsive When true, also generates sm, md, lg, xl and xxl versions.
state Pseudo-classes such as hover or focus, which generate classes like .opacity-hover-50.
css-var Generate a CSS custom property rule instead of a direct property.
important Add !important to the generated rules (utilities usually have it on).
print Also generate print versions, as with d-print-none.
rtl Set to false to skip the utility in right-to-left builds.

Two of them explain behavior you already know. responsive: true is why you can write mt-md-4 or text-lg-end: the generator copied the rules inside each media query and added the breakpoint to the name. And important is why a utility wins over a component style without a fight about specificity: utilities are marked !important so that one class reliably overrides whatever a component sets.

The class name pattern. With class: mt, a value key 3, and breakpoint md, the pieces join as mt-md-3. The infix (md) sits between the prefix and the value. When a value key is null the dash and value are dropped, which is how the plain .border and .shadow classes come about.

Seeing the effect in the browser

You cannot compile Sass here, but you can look at what the generator would write. The CSS below is hand-written to imitate the output for a "cursor" utility with responsive: true, and then used with classes exactly as you would use Bootstrap's.

What generated utilities look like

The classes work just like built-in ones because that is all a built-in utility is: a one-property rule with a predictable name.

Adding and changing utilities in Sass

In a Sass build you extend the map instead of editing Bootstrap's files. The shape below is the usual approach: import the functions and variables, merge your entries into $utilities, then import the rest of Bootstrap.

SCSS
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

$utilities: map-merge(
  $utilities,
  (
    "cursor": (
      property: cursor,
      class: cursor,
      responsive: true,
      values: auto pointer grab,
    ),
  )
);

@import "bootstrap/scss/utilities/api";

Adding values to an existing group works the same way; so does removing one, by setting a group to null in a merge. Bootstrap also provides map-get and map-merge helper patterns for editing a single group deeply, for example adding a new value to the width utility without touching the others. The exact import order matters because the utilities map must exist before you change it and the API partial must come after.

Every utility costs CSS bytes. A responsive utility with ten values produces roughly sixty rules (ten per breakpoint, six breakpoints). A few custom utilities are cheap, but a large responsive one with many values can add noticeably to the file. Turn on responsive only for utilities you will really use per breakpoint.

Pros and cons of utility-first

Utility classes are a style of writing CSS, and it helps to be honest about trade-offs.

Strengths

  • Speed. You style in the HTML without inventing names or jumping between files.
  • Consistency. Spacing, colors and sizes come from fixed scales, so pages look related by default.
  • Small, stable CSS. New pages reuse the same classes instead of adding new rules, so the stylesheet stops growing.
  • Safe changes. Editing one element's classes cannot break another page, which is hard to guarantee with shared custom classes.

Weaknesses

  • Long class lists. A busy element can have fifteen classes, which is noisy to read.
  • Repetition. The same set of classes repeated on many cards is a maintenance problem if the design changes.
  • Limits of the scale. If you need margin-top: 13px, the scale has no class for it.

Teams usually mix approaches. Use utilities for layout and one-off adjustments. When the same bundle repeats, extract it into a component: a template partial, a Blade or JavaScript component, or a small custom class that reuses Bootstrap's variables (padding: var(--bs-card-spacer-y)), rather than copying 15 classes around. Bootstrap's own @extend is discouraged because it makes the compiled CSS large and hard to follow.

Utilities for one-offs, a class for repeats

The shared look lives in one class; the colors and sizes of the numbers are one-off utilities. If the card design changes, you edit one rule. If one number needs another color, you add one class.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Where does Bootstrap define the list of utility groups that become classes?

    The $utilities Sass map holds the property, class prefix and values; a generator loops over it and prints the CSS.
  2. 2. What does responsive set to true do for a utility?

    The generator repeats the rules inside each media query and adds the breakpoint infix, giving classes like mt-md-3.
  3. 3. Why are utilities usually marked !important?

    A single class that always wins is what makes utilities predictable.
  4. 4. Which is a real weakness of utility-first CSS?

    Extract repeated bundles into components or a small shared class when the repetition becomes painful.

Summary

  • Almost all utilities come from the $utilities Sass map: property, class prefix, values, and options.
  • responsive, state, important, print and rtl control which variants the generator prints.
  • You extend utilities in Sass with map-merge before the API partial is imported; the examples here are read-only because the live editor has no Sass.
  • Utility-first gives speed and consistency but needs components for repeated bundles.
  • Keep custom utilities few: each responsive one multiplies the CSS.

Next lesson: Buttons.