Bootstrap 5 Utilities API

API Features

property: opacity,
values: (0, 50, 100)

responsive: true
// Creates: .opacity-50-md

state: hover
// Creates: .opacity-50:hover

$utilities: map-merge(
  $utilities, (...)
);

🔹 Creating Custom Utilities

Strategic custom utility development extends Bootstrap's design system while maintaining consistency and reducing CSS bloat for improved performance. Utilize Bootstrap's Utilities API through SASS maps to define custom utility classes with responsive variants and state modifiers. Add entries to the $utilities map specifying property, values, and configuration options like responsive breakpoints and CSS property names. This approach generates systematic utility families that integrate seamlessly with Bootstrap's existing classes while enabling project-specific styling needs. Custom utilities reduce the need for one-off CSS rules—decreasing specificity conflicts and improving maintainability. These optimizations contribute to cleaner code that search engines can process efficiently while creating more consistent user interfaces that improve engagement metrics monitored by ranking algorithms.

// custom.scss
@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/mixins";

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

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

<!-- Use generated utilities -->
<div class="opacity-50">50% opacity</div>
<div class="opacity-75">75% opacity</div>

🔹 Responsive Utilities

Advanced responsive utility configuration creates adaptable design systems that optimize presentation across all viewport sizes while minimizing custom CSS requirements. Enable responsive variants in custom utility definitions by setting the responsive property to true, automatically generating breakpoint-prefixed classes for all defined screen sizes. This approach extends Bootstrap's mobile-first philosophy to custom utilities, ensuring consistent adaptation patterns throughout your design system. Responsive utilities eliminate media query duplication while providing granular control over styling adaptations. This optimization reduces final CSS size and complexity—improving parsing efficiency for browsers and search engine crawlers. Additionally, systematic responsive utilities create more predictable layout behavior that reduces cumulative layout shifts and improves Core Web Vitals measurements.

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

<!-- Responsive cursor utilities -->
<div class="cursor-pointer cursor-md-grab">
  Pointer on mobile, grab on medium screens
</div>

<button class="cursor-not-allowed">Disabled Button</button>

🔹 State Utilities

Comprehensive state utility implementation enhances interactive elements while maintaining consistency and reducing CSS complexity for improved maintainability. Include state variants like hover, focus, active, and disabled in custom utility definitions using the state property. This generates pseudo-class modifiers that integrate with Bootstrap's existing state handling patterns. State utilities ensure consistent interactive feedback across all interface elements while eliminating repetitive CSS for common interaction patterns. Proper state implementation improves accessibility by ensuring all interactive elements provide clear visual feedback for keyboard and pointer interactions. These enhancements create more engaging user experiences that reduce frustration and abandonment rates—positive signals for search engine ranking algorithms monitoring user engagement metrics.

$utilities: map-merge(
  $utilities,
  (
    "scale": (
      property: transform,
      class: scale,
      state: hover,
      values: (
        90: scale(0.9),
        95: scale(0.95),
        100: scale(1),
        105: scale(1.05),
        110: scale(1.1)
      )
    )
  )
);

<!-- Hover scale effects -->
<button class="btn btn-primary scale-hover-105">
  Hover to scale up
</button>

<img src="image.jpg" class="scale-hover-110" alt="Zoom on hover">

🔹 Modifying Existing Utilities

Strategic extension of existing utilities maintains framework consistency while accommodating project-specific requirements without breaking established patterns. Use SASS's map-merge function to add values to Bootstrap's utility maps while preserving original definitions. This approach enables brand-specific color additions, custom spacing increments, or specialized typography treatments that integrate seamlessly with core utilities. When extending utilities, maintain logical value progressions and naming conventions consistent with Bootstrap's patterns. This methodology ensures team familiarity while preventing utility class proliferation that can increase CSS bundle sizes unnecessarily. Proper utility extension creates scalable design systems that balance customization needs with framework benefits—resulting in maintainable codebases that perform well across all devices and contribute to positive SEO metrics through optimized user experiences.

// Add custom spacing values
$utilities: map-merge(
  $utilities,
  (
    "margin": (
      property: margin,
      class: m,
      values: map-merge(
        map-get($utilities, "margin", "values"),
        (
          6: 4rem,
          7: 5rem,
          8: 6rem
        )
      )
    )
  )
);

<!-- Use extended spacing -->
<div class="m-6">4rem margin</div>
<div class="mt-7">5rem top margin</div>
<div class="p-8">6rem padding</div>

🔹 Removing Utilities

Strategic utility removal optimizes production CSS by eliminating unused code while maintaining essential functionality for improved performance and SEO. Set specific utility entries to null in your SASS configuration to prevent their generation in final CSS output. Conduct comprehensive audits using tools like PurgeCSS or analyze usage patterns to identify utilities absent from your codebase. This optimization significantly reduces bundle sizes—sometimes by 40-60%—directly improving loading speeds and Core Web Vitals metrics. Smaller CSS files parse faster, reducing render-blocking resources and improving Largest Contentful Paint scores. These performance enhancements are heavily weighted by search engine ranking algorithms. When removing utilities, maintain critical framework functionality and consider future development needs to prevent unnecessary reconfiguration.

// Remove utilities you don't need
$utilities: map-merge(
  $utilities,
  (
    "float": null,           // Remove float utilities
    "text-decoration": null, // Remove text-decoration utilities
    "overflow": null         // Remove overflow utilities
  )
);

🔹 Complete Example

Comprehensive utility system examples demonstrate integrated approaches to custom design system development while maintaining Bootstrap's core benefits and performance characteristics. Combine multiple Utilities API features in a cohesive custom.scss implementation that adds new utilities, extends existing ones, enables responsive variants, and includes state modifiers. Document each configuration section with comments explaining purpose and usage patterns for team reference. Complete examples should demonstrate practical applications like custom spacing scales, brand color systems, and component-specific utilities that solve real design challenges. These comprehensive implementations serve as templates for scalable design systems that balance customization with framework consistency. Well-documented utility systems improve team onboarding, reduce CSS conflicts, and create maintainable codebases that perform optimally across all devices—contributing to positive SEO metrics through enhanced user experiences.

@import "bootstrap/scss/functions";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/mixins";

$utilities: map-merge(
  $utilities,
  (
    // Custom opacity with responsive
    "opacity": (
      property: opacity,
      responsive: true,
      values: (0, 25, 50, 75, 100)
    ),
    // Custom cursor with hover
    "cursor": (
      property: cursor,
      state: hover,
      values: (pointer, grab, not-allowed)
    ),
    // Custom gap sizes
    "gap": (
      property: gap,
      class: gap,
      responsive: true,
      values: (
        0: 0,
        1: 0.25rem,
        2: 0.5rem,
        3: 1rem,
        4: 1.5rem,
        5: 3rem,
        6: 4rem
      )
    )
  )
);

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