Skip to main content

Customize

Components

Extend the theme — add a theme color, add utilities through the API, and build a new component with no JavaScript.

Three ways to extend

  1. Add a theme color. Merge into the theme maps and every .btn-*, .bg-*, .alert-* … appears.
  2. Add a utility. Merge into $utilities and the API generates the classes, responsive variants included.
  3. Add a component. Native element first, @supports enhancement second, no script ever.

All three happen in Sass, before or between the theme's imports. See Import parts for where each hook sits.

Adding a theme color

This is exactly how gold, navy and cream are added in scss/_maps.scss. Bootstrap keeps six maps per color (base, text-emphasis, bg-subtle, border-subtle, and the dark versions of the last three). Merge into all six and the color behaves like a built-in one in both modes.

// _maps.scss — loaded after Bootstrap's variables, before Bootstrap's maps
$rb-theme-colors: (
  "gold": $rb-gold-500,
  "navy": $rb-navy-700,
  "cream": $rb-cream-100,
);
$theme-colors: map-merge($theme-colors, $rb-theme-colors);

$theme-colors-text: map-merge($theme-colors-text, (
  "gold": #6b5410,
  "navy": $rb-navy-900,
  "cream": $rb-navy-700,
));
$theme-colors-bg-subtle: map-merge($theme-colors-bg-subtle, (
  "gold": #f3e8c3,
  "navy": $rb-navy-50,
  "cream": $rb-cream-50,
));
$theme-colors-border-subtle: map-merge($theme-colors-border-subtle, (
  "gold": $rb-gold-300,
  "navy": $rb-navy-100,
  "cream": $rb-cream-300,
));

$theme-colors-text-dark: map-merge($theme-colors-text-dark, (
  "gold": $rb-gold-300,
  "navy": $rb-navy-100,
  "cream": $rb-cream-50,
));
$theme-colors-bg-subtle-dark: map-merge($theme-colors-bg-subtle-dark, (
  "gold": #3a2f0a,
  "navy": $rb-navy-700,
  "cream": #2b2614,
));
$theme-colors-border-subtle-dark: map-merge($theme-colors-border-subtle-dark, (
  "gold": $rb-gold-700,
  "navy": $rb-navy-500,
  "cream": #5c5230,
));

To add a fourth — say a Nitro orange for a special-event page — copy the pattern with one key. Pick the emphasis value so it clears 4.5:1 on the body background of each mode, and let color-contrast() choose the button text.

$rb-orange-500: #e8641b;

@import "@ropebreak/bootstrap/scss/palette";
@import "@ropebreak/bootstrap/scss/fonts";
@import "bootstrap/scss/functions";
@import "@ropebreak/bootstrap/scss/variables";
@import "@ropebreak/bootstrap/scss/variables-dark";
@import "bootstrap/scss/variables";
@import "bootstrap/scss/variables-dark";
@import "@ropebreak/bootstrap/scss/maps";

$theme-colors: map-merge($theme-colors, ("nitro": $rb-orange-500));
$theme-colors-text: map-merge($theme-colors-text, ("nitro": #7a2e00));
$theme-colors-bg-subtle: map-merge($theme-colors-bg-subtle, ("nitro": #fbe3d3));
$theme-colors-border-subtle: map-merge($theme-colors-border-subtle, ("nitro": #f4b089));
$theme-colors-text-dark: map-merge($theme-colors-text-dark, ("nitro": #ffb085));
$theme-colors-bg-subtle-dark: map-merge($theme-colors-bg-subtle-dark, ("nitro": #3d1a06));
$theme-colors-border-subtle-dark: map-merge($theme-colors-border-subtle-dark, ("nitro": #8a3a0e));

@import "bootstrap/scss/maps";
// … the rest of the entry, unchanged

You get .btn-nitro, .btn-outline-nitro, .bg-nitro, .text-nitro, .text-bg-nitro, .border-nitro, .link-nitro, .alert-nitro, .list-group-item-nitro, .focus-ring-nitro and the --bs-nitro* variables. What you do not get are .text-nitro-emphasis, .bg-nitro-subtle and .border-nitro-subtle: Bootstrap builds those utilities from fixed eight-entry maps ($utilities-text-emphasis-colors, $utilities-bg-subtle, $utilities-border-subtle). Merge into those too if you want the classes. The theme's own extras currently stop at the variables; see Color.

Adding utilities

scss/_utilities.scss loads after Bootstrap's _utilities.scss and before the API, so a map-merge there either extends an existing utility or adds a new one. The theme adds five.

$utilities: map-merge($utilities, (
  // extend: .font-display joins .font-monospace
  "font-family": map-merge(map-get($utilities, "font-family"), (
    values: (
      monospace: var(--#{$prefix}font-monospace),
      display: var(--#{$prefix}font-display),
    ),
  )),

  // extend: .fw-black joins the weight scale
  "font-weight": map-merge(map-get($utilities, "font-weight"), (
    values: map-merge(map-get(map-get($utilities, "font-weight"), "values"), ("black": 800)),
  )),

  // new
  "letter-spacing": (
    property: letter-spacing,
    class: ls,
    values: (tight: 0, display: 0.01em, wide: 0.08em),
  ),
  "transition": (
    property: transition,
    class: transition,
    values: (
      base: var(--#{$prefix}transition-base),
      fade: var(--#{$prefix}transition-fade),
      none: none,
    ),
  ),
  "scroll-snap": (
    property: scroll-snap-type,
    class: snap,
    values: (x: x mandatory, y: y mandatory, both: both mandatory, none: none),
  ),
));
ClassDeclaration
.font-displayfont-family: var(--bs-font-display)
.fw-blackfont-weight: 800
.ls-tight / .ls-display / .ls-wideletter-spacing: 0 / 0.01em / 0.08em
.transition-base / .transition-fade / .transition-nonetransition: var(--bs-transition-base) / var(--bs-transition-fade) / none
.snap-x / .snap-y / .snap-both / .snap-nonescroll-snap-type: x mandatory / y mandatory / both mandatory / none

.font-display .fw-black .ls-display

.font-monospace .ls-wide — eyebrow text

.snap-x — 1
2
3
HTML
<p class="font-display fw-black ls-display fs-1 text-uppercase mb-2">.font-display .fw-black .ls-display</p>
<p class="font-monospace ls-wide text-uppercase small mb-3">.font-monospace .ls-wide — eyebrow text</p>
<div class="d-flex gap-2 mb-3">
  <button type="button" class="btn btn-outline-primary transition-base">.transition-base</button>
  <button type="button" class="btn btn-outline-primary transition-none">.transition-none</button>
</div>
<div class="d-flex overflow-auto snap-x gap-3" style="scroll-padding: 0 1rem">
  <div class="flex-shrink-0 w-75 p-4 text-bg-navy rounded" style="scroll-snap-align: start">.snap-x — 1</div>
  <div class="flex-shrink-0 w-75 p-4 text-bg-gold rounded" style="scroll-snap-align: start">2</div>
  <div class="flex-shrink-0 w-75 p-4 text-bg-cream rounded" style="scroll-snap-align: start">3</div>
</div>

None of these are responsive. Add responsive: true to a utility entry to get .ls-md-wide and friends. The API reference is on Utilities API.

// Your own: a text-shadow utility for marquee headings
$utilities: map-merge($utilities, (
  "text-shadow": (
    property: text-shadow,
    class: text-shadow,
    values: (
      marquee: 0 2px 0 rgba(10, 27, 61, 0.4),
      none: none,
    ),
  ),
));

Building a no-JS component

Every component in scss/components/ follows the same shape. Copy it.

  1. Pick the native element that already has the behaviour: <details> for toggling, a popover attribute for overlays, <dialog> for dismissal, radios for exclusive state, scroll-snap for sliding.
  2. Style the baseline with plain, widely-supported CSS. It must be complete on its own.
  3. Enhance inside @supports. Engines that pass the test get the animation or positioning; others skip the block and lose nothing but polish.
  4. Respect reduced motion by using the shared transition variables, or by zeroing yours in the same media query.
  5. Hand off to the component variables so people can retheme with inline styles.

A worked example: a "spoiler" that hides a match result until the reader asks.

// _spoiler.scss
.spoiler {
  --#{$prefix}spoiler-bg: var(--#{$prefix}tertiary-bg);
  --#{$prefix}spoiler-border: var(--#{$prefix}border-color);

  border: 1px solid var(--#{$prefix}spoiler-border);
  border-radius: var(--#{$prefix}border-radius-sm);
  background: var(--#{$prefix}spoiler-bg);
}

// 1–2. Baseline: a <details>; the summary is a small outline button
.spoiler > summary {
  @extend .btn;
  @extend .btn-sm;
  @extend .btn-outline-secondary;

  margin: var(--#{$prefix}spacer, 1rem);
  list-style: none;

  &::-webkit-details-marker { display: none; }
  &::after { content: " ▸"; }
}

.spoiler[open] > summary::after { content: " ▾"; }

.spoiler-body {
  padding: 0 var(--space-4) var(--space-4);
}

// 3. Enhancement: animate the reveal where ::details-content exists
@supports selector(details::details-content) {
  .spoiler { interpolate-size: allow-keywords; }

  .spoiler::details-content {
    height: 0;
    overflow: clip;
    transition:
      var(--#{$prefix}transition-collapse),
      content-visibility $rb-duration-slow $rb-ease-standard;
    transition-behavior: allow-discrete;
  }

  .spoiler[open]::details-content { height: auto; }
}

// 4. Reduced motion is already handled: --bs-transition-collapse is `none`
//    under prefers-reduced-motion, so the transition collapses to nothing.

The same thing in markup, using what the theme already ships (the collapse styles do the animation here):

Show the result

Hogan def. Andre the Giant by pinfall at 12:01.

The slam heard round the world. Attendance 93,173.

HTML
<details class="collapse border rounded-1 bg-body-tertiary" id="cmp-spoiler">
  <summary class="btn btn-sm btn-outline-secondary m-4">Show the result</summary>
  <div class="px-4 pb-4">
    <p class="mb-1"><strong>Hogan</strong> def. Andre the Giant by pinfall at 12:01.</p>
    <p class="mb-0 text-body-secondary small">The slam heard round the world. Attendance 93,173.</p>
  </div>
</details>

Checklist before you ship a component:

  • Does it work with every @supports block deleted?
  • Does the keyboard reach and operate it with no extra attributes?
  • Does it read --bs-* variables rather than palette hex, so it follows color modes?
  • Did you add any new property or pseudo-element to .stylelintrc.json?
  • Is there a docs page, with the markup in the file's header comment?

Patterns to borrow: components/_transitions.scss for ::details-content, components/_popover.scss for anchor positioning with a centred fallback, components/_toast.scss for @starting-style, components/_tabs.scss for index pairing with :has(). Read them with No JavaScript open.