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
- Add a theme color. Merge into the theme maps and every
.btn-*,.bg-*,.alert-*… appears. - Add a utility. Merge into
$utilitiesand the API generates the classes, responsive variants included. - Add a component. Native element first,
@supportsenhancement 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),
),
));
| Class | Declaration |
|---|---|
.font-display | font-family: var(--bs-font-display) |
.fw-black | font-weight: 800 |
.ls-tight / .ls-display / .ls-wide | letter-spacing: 0 / 0.01em / 0.08em |
.transition-base / .transition-fade / .transition-none | transition: var(--bs-transition-base) / var(--bs-transition-fade) / none |
.snap-x / .snap-y / .snap-both / .snap-none | scroll-snap-type: x mandatory / y mandatory / both mandatory / none |
.font-display .fw-black .ls-display
.font-monospace .ls-wide — eyebrow text
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.
- Pick the native element that already has the behaviour:
<details>for toggling, apopoverattribute for overlays,<dialog>for dismissal, radios for exclusive state, scroll-snap for sliding. - Style the baseline with plain, widely-supported CSS. It must be complete on its own.
- Enhance inside
@supports. Engines that pass the test get the animation or positioning; others skip the block and lose nothing but polish. - Respect reduced motion by using the shared transition variables, or by zeroing yours in the same media query.
- 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
@supportsblock 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.