Utility API

Source: https://getbootstrap.com/docs/6.0/utilities/api

The utility API is a Sass-based tool to generate utility classes.

Bootstrap utilities are generated with our utility API and can be used to modify or extend our default set of utility classes via Sass. Our utility API is based on a series of Sass maps and functions for generating families of classes with various options. If you’re unfamiliar with Sass maps, read up on the official Sass docs to get started.

The $utilities map contains all our utilities and is later merged with your custom $utilities map, if present. The utility map contains a keyed list of utility groups which accept the following options:

Option Type Default value Description
property Required – Name of the property. Can be a string, a space-separated list of strings (e.g., horizontal paddings or margins), or a map of property-to-default-value pairs (see Property-Value Mapping).
values Required – List of values, or a map if you don’t want the class name to be the same as the value. If null is used as map key, class is not prepended to the class name.
selector Optional class Type of CSS selector in the generated CSS ruleset. Can be class, attr-starts, or attr-includes.
child-selector Optional null A child/descendant selector appended to the utility’s selector, wrapped in :where() for zero specificity. Use to target children instead of the element itself.
class Optional null Name of the generated class. If not provided and property is an array of strings, class will default to the first element of the property array. If not provided and property is a string, the values keys are used for the class names.
variables Optional null List or map of CSS custom properties to generate within each utility class. When a list, each variable receives the utility value. When a map, the provided static values are used.
state Optional null List of pseudo-class variants (e.g., :hover or :focus) to generate as prefix-style classes.
responsive Optional false Boolean indicating if responsive classes should be generated.
important Optional false Boolean indicating if !important should be added to the utility’s CSS rules.
print Optional false Boolean indicating if print classes need to be generated.
dark Optional false Boolean indicating if dark: prefixed classes should be generated, scoped to @media (prefers-color-scheme: dark).
enabled Optional true Set to false to suppress output for a utility while keeping its definition in the $utilities map.

API explained

All utility variables are added to the $utilities variable within our _utilities.scss stylesheet, which is a giant, nested Sass map. Each group of utility classes are generated from a block that looks something like this:

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

Which outputs the following:

.opacity-0 { opacity: 0; }
.opacity-25 { opacity: .25; }
.opacity-50 { opacity: .5; }
.opacity-75 { opacity: .75; }
.opacity-100 { opacity: 1; }

property

<div class="badge badge-subtle theme-danger fs-sm fw-normal align-self-start">Required</div>

The property key must be set for any utility, and it must contain a valid CSS property. This property is used in the generated utility’s ruleset. When the class key is omitted, it also serves as the default class name. Consider the text-decoration utility:

$utilities: (
  "text-decoration": (
    property: text-decoration,
    values: none underline line-through
  )
);

Output:

.text-decoration-none { text-decoration: none; }
.text-decoration-underline { text-decoration: underline; }
.text-decoration-line-through { text-decoration: line-through; }

Property value mapping

The property key also accepts a map of CSS property names to default values. This lets a single utility class set multiple properties at once, and lets values override individual properties when the value is itself a map.

When a property's default value in the map is null, the utility value is used directly for that property. When a default value is set, it is used unless the utility's value map contains a matching key.

A common pattern is pairing a CSS custom property (which receives the utility value) with a regular property that references it:

$utilities: (
  "bg-color": (
    property: (
      "--bg": null,
      "background-color": var(--bg)
    ),
    class: bg,
    values: (
      primary: var(--blue-500),
      danger:  var(--red-500),
    )
  )
);

Output:

.bg-primary { --bs-bg: var(--bs-blue-500); background-color: var(--bs-bg); }
.bg-danger  { --bs-bg: var(--bs-red-500);  background-color: var(--bs-bg); }

Source CSS variables are used without a --bs- prefix, which is added in our compiled CSS with our PostCSS plugin.

You can also set per-value overrides. When values contains a nested map whose keys match properties in the property map, those values are used for the matching property:

$utilities: (
  "text-size": (
    property: (
      "font-size":   1rem,
      "line-height": 1.5
    ),
    class: text,
    values: (
      "sm": ("font-size": .875rem, "line-height": 1.25),
      "lg": ("font-size": 1.25rem, "line-height": 1.75),
    )
  )
);

Output:

.text-sm { font-size: .875rem; line-height: 1.25; }
.text-lg { font-size: 1.25rem; line-height: 1.75; }

values

<div class="badge badge-subtle theme-danger fs-sm fw-normal align-self-start">Required</div>

Use the values key to specify which values for the specified property should be used in the generated class names and rules. Can be a list or map (set in the utilities or in a Sass variable).

As a list, like with text-decoration utilities:

values: none underline line-through

As a map, like with opacity utilities:

values: (
  0: 0,
  25: .25,
  50: .5,
  75: .75,
  100: 1,
)

As a Sass variable that sets the list or map, as in our position utilities:

values: $position-values

selector

Option Description
No selector Defaults to "class"
"class" Matches elements with a class that matches the specified value
"attr-starts" Matches elements with a class that starts with a string
"attr-includes" Matches elements with a class that includes a string

Use the selector option to change the CSS selector used in the generated CSS ruleset. The default option is to generate a class selector. When using an attribute selector—either attr-starts or attr-includes—the class option is required. We use these internally to simplify the construction of other utilities.

For attribute selectors, you’ll most likely want the attr-includes as the starting attribute selector in CSS applies to the entire string of classes in an attribute’s value. For example, [class^="name"] would not match class="example name".

As an example, to change from .ratio-* to [class*="ratio-"]:

$utilities: (
  // Create an attribute selector utility
  "aspect-ratio-attr": (
    selector: "attr-includes",
    class: "ratio-",
    property: aspect-ratio,
    values: var(--ratio),
  ),
  // Create a CSS variable utility that matches the attribute selector utility
  "aspect-ratio": (
    property: --ratio,
    class: ratio,
    values: $aspect-ratios
  ),
);

Note that the --ratio custom property will automatically be prefixed to --bs-ratio in the compiled CSS via PostCSS.

Which outputs the following:

[class*="ratio-"] { aspect-ratio: var(--bs-ratio); }
.ratio-auto { --bs-ratio: auto; }
.ratio-1x1 { --bs-ratio: 1 / 1; }
.ratio-4x3 { --bs-ratio: 4 / 3; }
.ratio-16x9 { --bs-ratio: 16 / 9; }
.ratio-21x9 { --bs-ratio: 21 / 9; }

child-selector

Use the child-selector option to apply a CSS property to children of the element with the utility class rather than the element itself. The generated selector is wrapped in :where() for zero specificity, making it easy to override. This powers our built-in space-x/y and divide-x/y utilities.

For example, our space-x utility uses child-selector to add horizontal spacing between direct children:

$utilities: (
  "space-x": (
    property: margin-inline-end,
    class: space-x,
    child-selector: "> :not(:last-child)",
    values: $spacers
  )
);

Output includes:

:where(.space-x-1 > :not(:last-child)) { margin-inline-end: .25rem; }
:where(.space-x-2 > :not(:last-child)) { margin-inline-end: .375rem; }
:where(.space-x-3 > :not(:last-child)) { margin-inline-end: .5rem; }
/* ...through .space-x-12 */

The child-selector value can be any valid CSS selector. For example, you could create a striped row utility using :nth-child():

$utilities: (
  "striped-bg": (
    property: background-color,
    class: striped,
    child-selector: "> :nth-child(odd)",
    values: (
      null: var(--bs-bg-1),
    )
  )
);

Output:

:where(.striped > :nth-child(odd)) { background-color: var(--bs-bg-1); }

Or target all direct children with > *:

$utilities: (
  "child-rounded": (
    property: border-radius,
    class: child-rounded,
    child-selector: "> *",
    values: (
      null: var(--bs-border-radius),
      0: 0,
    )
  )
);

Output:

:where(.child-rounded > *) { border-radius: var(--bs-border-radius); }
:where(.child-rounded-0 > *) { border-radius: 0; }

class

Use the class option to change the class prefix used in the compiled CSS. For example, to change from .opacity-* to .o-*:

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

Output:

.o-0 { opacity: 0; }
.o-25 { opacity: .25; }
.o-50 { opacity: .5; }
.o-75 { opacity: .75; }
.o-100 { opacity: 1; }

If class: null, generates classes for each of the values keys:

$utilities: (
  "visibility": (
    property: visibility,
    class: null,
    values: (
      visible: visible,
      invisible: hidden,
    )
  )
);

Output:

.visible { visibility: visible; }
.invisible { visibility: hidden; }

Variables

Use the variables option to generate CSS custom properties within each utility class’s ruleset. The value can be either a list or a map.

When variables is a list, each variable receives the current utility value:

$utilities: (
  "link-opacity": (
    property: color,
    class: link,
    variables: link-color,
    values: (
      10: 10%,
      50: 50%,
      100: 100%,
    )
  ),
);

Output:

.link-10 { --bs-link-color: 10%; color: 10%; }
.link-50 { --bs-link-color: 50%; color: 50%; }
.link-100 { --bs-link-color: 100%; color: 100%; }

When variables is a map, the provided static values are used on every generated class:

$utilities: (
  "link-underline": (
    property: text-decoration-color,
    class: link-underline,
    variables: (
      "link-underline-opacity": 1
    ),
    values: (...)
  )
);

Output:

.link-underline-primary {
  --bs-link-underline-opacity: 1;
  text-decoration-color: ...;
}

States

Use the state option to generate pseudo-class variations. Example pseudo-classes are :hover and :focus. When a list of states are provided, classnames are created for that pseudo-class with a prefix-style syntax matching the responsive prefix pattern. For example, to change opacity on hover, add state: hover and you’ll get .hover\:opacity:hover in your compiled CSS.