Utility API and Utility Classes in Bootstrap 5

What is Utility API and Utility Classes in Bootstrap

Utility API is a Sass-based tool for creating utility classes.
Utility classes are small, single-purpose classes that can be used to quickly apply styles to HTML elements without the need to write custom CSS.

Bootstrap has bootstrap/scss/utilities/api and bootstrap/scss/utilities, which allow you to create your own utilities (higher-order classes) for rapid prototyping and responsive design. In principle, it is similar to tailwind, but with fewer classes and a simpler system.

$utilities is an array-like object in SASS that contains settings for generating utility classes. It holds a list of all the utilities (classes) that will be generated in the final CSS file and their configurations. The Utilities API generates classes based on the data from $utilities.

In _utilities.scss, there is an array-like object $utilities with a set of properties and data for generating utility classes.

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

The generated utility classes have a higher priority than the basic bootstrap classes. From the names of the utility classes, it is usually clear what this class does. For example, .text-center centers the text, .m-3 adds margins, .d-flex makes an element a flex container, etc.

The advantage of using utility classes is that they allow for quick creation of responsive designs without the need to write a lot of custom CSS code.

Basic principles of such utility classes:

Atomic independent classes
Can be combined with each other
Have a higher priority than the base Bootstrap classes

Disadvantages: The size of the final CSS file increases, as many classes that may not be used in the project are generated. Customization and refactoring can also be more challenging, as you have to work with a large number of classes. For example, if you need to change the text color, you would have to find and replace all .text-* classes used in the project, instead of changing it once in the CSS file. Additionally, another drawback is that the multitude of classes for each element can complicate the HTML markup.

Properties for Each Utility

Option	Type	Description
`property`	Required	Property name, which can be a string or an array of strings (e.g., horizontal padding or margins).
`values`	Required	List of values or a map, if you do not want the class name to match the value. If `null` is used as a key in the map, it will not be compiled.
`class`	Optional	Variable for class name, if you do not want it to match the property. If the `class` key is not specified, and the `property` key is an array of strings, the class name will be the first element of the `property` array.
`state`	Optional	List of pseudo-class variations, such as `:hover` or `:focus`, to be generated for the utility. Default is none.
`responsive`	Optional	Boolean indicating whether to generate responsive classes. Default is `false`.
`rfs`	Optional	Boolean value for enabling fluid rescaling. See page on RFS for more details. Default is `false`.
`print`	Optional	Boolean indicating whether to generate print classes. Default is `false`.
`rtl`	Optional	Boolean indicating whether the utility should be supported in RTL. Default is `true`.

N.B.
All utility classes generated by the API include !important to ensure they override components and modifier classes by design. You can toggle this setting globally using the variable $enable-important-utilities (default is true).

Utilities Can Be Extended.

For this, we use the Sass function map-merge(), which allows merging two maps into one.

$utilities: map-merge(
	$utilities,
	(
		"custom-utility": (
			property: custom-property,
			class: custom-class,
			values: (
				key1: value1,
				key2: value2,
			)
		)
	)
);

Order matters, first you need to declare $utilities, then extend it, and after that initialize utilities/api.

@import "bootstrap/scss/utilities";  
$utilities: map-merge(  
   $utilities,  
   (  
   "height": (  
     property: height,  
     class: h,  
     responsive: true,  
     values: (  
       25: 25%,  
       50: 50%,  
       75: 75%,  
       100: 100%  
     )  
   )  
   )  
);  
@import "bootstrap/scss/utilities/api";

Existing Utilities Can Be Modified.

For this, we also use map-merge(), but with the existing utility, and map-get() to retrieve the required properties.

For example, to add 10% to the width utility.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";
 
$utilities: map-merge(
  $utilities,
  (
    "width": map-merge(
      map-get($utilities, "width"),
      (
        values: map-merge(
          map-get(map-get($utilities, "width"), "values"),
          (10: 10%),
        ),
      ),
    ),
  )
);

Add Responsive to Existing Utility Class.

In Bootstrap 5, all utilities can be “customized” for breakpoints.

{property}{sides?}-{breakpoint?}-{value}

For example:
d-flex, d-sm-flex, d-md-flex, d-lg-flex

<div class="d-lg-flex">
  Responsive height block
</div>

However, Bootstrap 5 does not support responsive breakpoints “out of the box” for all utilities.

For margin, padding, display, flex, grid, text, color — yes, they work with -sm-, -md-, etc.
But for height/width (h-*, w-*) responsive versions are not available by default. Therefore, h-md-100 will not work.

But there’s a way to add responsive support to existing utilities, such as height and width, by adding the property responsive: true in the utility definition in $utilities.

$utilities: map-merge(  
   $utilities,  
   (  
   "height": (  
     property: height,  
     class: h,  
     responsive: true,  
     values: (  
       25: 25%,  
       50: 50%,  
       75: 75%,  
       100: 100%  
     )  
   )  
   )  
);

Alternatively, you can precisely rewrite a specific utility class, for example, border.

$utilities: map-merge(
  $utilities, (
    "border": map-merge(
      map-get($utilities, "border"),
      ( responsive: true ),
    ),
  )
)

Renaming Utility Classes

This is also possible if you don’t like the default class name. This is controlled by the class property.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";
 
$utilities: map-merge(
  $utilities, (
    "margin-start": map-merge(
      map-get($utilities, "margin-start"),
      ( class: ml ),
    ),
  )
);

Remove Specific Utility Classes from CSS Generation

You can remove any utilities by setting the group key to null. For example, here’s how to remove the width utility.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/utilities";
 
$utilities: map-merge(
  $utilities,
  (
    "width": null
  )
);

Levy's Notes

Explorer