Bootstrap Utility API

Understanding Utility Classes

Before diving into the Utility API, let's understand what utility classes are and why they're useful.

What Are Utility Classes?

Utility classes are single-purpose CSS classes that apply a specific style to an element. They follow a functional CSS approach, where each class does one thing and does it well.

/* CSS */
.button {
  display: inline-block;
  padding: 0.5rem 1rem;
  margin-top: 1rem;
  background-color: blue;
  color: white;
  border-radius: 0.25rem;
}

/* HTML */
<button class="button">Click Me</button>

/* HTML with utility classes */
<button class="d-inline-block p-3 mt-3 bg-primary text-white rounded">
  Click Me
</button>

Benefits of Utility Classes

• Rapid development without writing custom CSS
• Consistent spacing, sizing, and color values
• Reduced CSS file size (when using only what you need)
• Easier maintenance with less context switching
• More predictable CSS with less specificity issues

The Utility API Structure

The Bootstrap Utility API is a Sass map that defines how utility classes are generated. Each utility has a set of configuration options that determine its behavior.

API Configuration Options

Example API Definition

Here's how the margin utility is defined in Bootstrap's Utility API:

$utilities: (
  "margin": (
    responsive: true,
    property: margin,
    class: m,
    values: map-merge($spacers, (auto: auto))
  ),
  "margin-x": (
    responsive: true,
    property: margin-right margin-left,
    class: mx,
    values: map-merge($spacers, (auto: auto))
  ),
  "margin-y": (
    responsive: true,
    property: margin-top margin-bottom,
    class: my,
    values: map-merge($spacers, (auto: auto))
  ),
  "margin-top": (
    responsive: true,
    property: margin-top,
    class: mt,
    values: map-merge($spacers, (auto: auto))
  ),
  // ... more margin utilities
);

Creating Custom Utilities

One of the most powerful features of the Utility API is the ability to create your own custom utilities.

Basic Custom Utility

Let's create a simple custom utility for setting opacity:

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

// Add a new utility to the utilities map
$utilities: map-merge(
  $utilities,
  (
    "opacity": (
      property: opacity,
      class: opacity,
      values: (
        0: 0,
        25: .25,
        50: .5,
        75: .75,
        100: 1,
      )
    )
  )
);

// Import Bootstrap utilities API
@import "bootstrap/scss/utilities/api";

This will generate the following classes:

• .opacity-0 - Sets opacity to 0
• .opacity-25 - Sets opacity to 0.25
• .opacity-50 - Sets opacity to 0.5
• .opacity-75 - Sets opacity to 0.75
• .opacity-100 - Sets opacity to 1

Custom Utility with Responsive Variants

Let's create a custom utility for text size with responsive variants:

$utilities: map-merge(
  $utilities,
  (
    "text-size": (
      responsive: true,
      property: font-size,
      class: text,
      values: (
        xs: 0.75rem,
        sm: 0.875rem,
        md: 1rem,
        lg: 1.25rem,
        xl: 1.5rem,
      )
    )
  )
);

This will generate classes like:

• .text-xs, .text-sm, .text-md, etc.
• .text-sm-xs, .text-md-sm, .text-lg-md, etc.

Advanced Utility API Features

Multiple Properties

You can create utilities that affect multiple CSS properties:

$utilities: map-merge(
  $utilities,
  (
    "flex-center": (
      property: display flex-direction justify-content align-items,
      class: flex-center,
      values: (
        center: flex column center center,
      )
    )
  )
);

State Variants

Create utilities that apply on hover, focus, or other states:

$utilities: map-merge(
  $utilities,
  (
    "background-color": (
      property: background-color,
      class: bg,
      values: map-merge(
        $theme-colors,
        (
          "body": $body-bg,
          "white": $white,
          "transparent": transparent
        )
      ),
      state: hover focus
    )
  )
);

This will generate classes like .bg-primary-hover and .bg-primary-focus.

CSS Variable Utilities

Create utilities that set CSS custom properties:

$utilities: map-merge(
  $utilities,
  (
    "theme-color": (
      property: --theme-color,
      class: theme,
      values: map-merge(
        $theme-colors,
        (
          "custom": #ff6b6b,
        )
      ),
    )
  )
);

Modifying Existing Utilities

You can also modify Bootstrap's existing utilities to add or remove values.

Adding Values to Existing Utilities

Add custom values to the spacing utilities:

// Create a custom spacer value
$custom-spacers: (
  6: $spacer * 4,
  7: $spacer * 5,
  8: $spacer * 6,
);

// Add custom spacers to the existing spacers map
$spacers: map-merge($spacers, $custom-spacers);

// The utilities API will automatically use the updated $spacers map

Removing Utilities

Remove utilities you don't need to reduce CSS file size:

// Remove float utilities
$utilities: map-merge(
  $utilities,
  (
    "float": null
  )
);

Modifying Utility Options

Change how existing utilities behave:

// Make the position utility not responsive
$utilities: map-merge(
  $utilities,
  (
    "position": (
      property: position,
      responsive: false,
      values: static relative absolute fixed sticky
    )
  )
);

Real-World Examples

Example 1: Custom Z-Index Utilities

$utilities: map-merge(
  $utilities,
  (
    "z-index": (
      property: z-index,
      class: z,
      values: (
        n1: -1,
        0: 0,
        1: 1,
        10: 10,
        100: 100,
        1000: 1000,
        auto: auto
      )
    )
  )
);

Example 2: Custom Border Radius Utilities

$utilities: map-merge(
  $utilities,
  (
    "border-radius-custom": (
      property: border-radius,
      class: rounded-custom,
      values: (
        xs: 0.125rem,
        sm: 0.25rem,
        md: 0.5rem,
        lg: 1rem,
        xl: 2rem,
        pill: 50rem,
      )
    )
  )
);

Example 3: Custom Animation Utilities

// Define animations in your CSS
@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slideIn {
  from { transform: translateY(20px); opacity: 0; }
  to { transform: translateY(0); opacity: 1; }
}

// Create animation utilities
$utilities: map-merge(
  $utilities,
  (
    "animation": (
      property: animation,
      class: anim,
      values: (
        none: none,
        fade: fadeIn 0.5s ease,
        slide: slideIn 0.5s ease,
        pulse: pulse 2s infinite,
      )
    )
  )
);

Best Practices

Complete Example: Building a Custom Utility System

Let's put it all together and create a custom utility system for a fictional project:

// _custom-utilities.scss

// 1. Include Bootstrap functions, variables, and mixins
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "bootstrap/scss/maps";
@import "bootstrap/scss/mixins";
@import "bootstrap/scss/utilities";

// 2. Define custom values
$custom-colors: (
  "primary-light": tint-color($primary, 40%),
  "primary-dark": shade-color($primary, 40%),
  "brand-blue": #1e88e5,
  "brand-green": #43a047,
  "brand-purple": #8e24aa
);

$custom-spacers: (
  6: $spacer * 4,
  7: $spacer * 5,
  8: $spacer * 6
);

// 3. Merge custom values with Bootstrap's defaults
$theme-colors: map-merge($theme-colors, $custom-colors);
$spacers: map-merge($spacers, $custom-spacers);

// 4. Define custom utilities
$custom-utilities: (
  // Custom z-index utility
  "z-index": (
    property: z-index,
    class: z,
    values: (
      n1: -1,
      0: 0,
      1: 1,
      10: 10,
      100: 100,
      1000: 1000,
      auto: auto
    )
  ),
  
  // Custom text shadow utility
  "text-shadow": (
    property: text-shadow,
    class: text-shadow,
    values: (
      sm: 0 1px 2px rgba(0, 0, 0, 0.1),
      md: 0 2px 4px rgba(0, 0, 0, 0.1),
      lg: 0 4px 8px rgba(0, 0, 0, 0.1),
      none: none
    )
  ),
  
  // Custom animation utility
  "animation": (
    property: animation,
    class: anim,
    values: (
      none: none,
      fade: fadeIn 0.5s ease,
      slide: slideIn 0.5s ease,
      pulse: pulse 2s infinite
    )
  ),
  
  // Custom gradient backgrounds
  "gradient": (
    property: background,
    class: bg-gradient,
    values: (
      primary: linear-gradient(45deg, $primary, tint-color($primary, 40%)),
      success: linear-gradient(45deg, $success, tint-color($success, 40%)),
      info: linear-gradient(45deg, $info, tint-color($info, 40%)),
      brand: linear-gradient(45deg, map-get($custom-colors, "brand-blue"), map-get($custom-colors, "brand-purple"))
    )
  )
);

// 5. Modify existing utilities
$utilities: map-merge(
  $utilities,
  (
    // Add hover state to background colors
    "background-color": (
      property: background-color,
      class: bg,
      values: map-merge(
        $theme-colors,
        (
          "body": $body-bg,
          "white": $white,
          "transparent": transparent
        )
      ),
      state: hover
    ),
    
    // Remove float utilities (if not needed)
    "float": null
  )
);

// 6. Merge custom utilities with Bootstrap utilities
$utilities: map-merge($utilities, $custom-utilities);

// 7. Import Bootstrap utilities API to generate the classes
@import "bootstrap/scss/utilities/api";

Resources