Skip to main content

Customize

CSS variables

The custom properties the theme adds on the root, the component variables it leaves alone, and how to override either.

Root variables

Bootstrap 5.3 publishes its globals as --bs-* custom properties on :root. The theme keeps every one of them (with RopeBreak.net values) and adds the following. All of them are declared on :root, [data-bs-theme="light"], and the ones that change in dark mode are redeclared under [data-bs-theme="dark"] and the automatic prefers-color-scheme rule.

AddedValuesSource
--bs-gold, --bs-navy, --bs-cream (+ -rgb, -text-emphasis, -bg-subtle, -border-subtle)Extra theme colorsscss/_maps.scss
--bs-navy-50 … --bs-navy-900, --bs-gold-300/500/700, --bs-cream-50/100/300, --bs-red-600, --bs-green-600Raw palette via $colorsscss/_maps.scss
--bs-font-displayBig Shoulders Display, then the sans stackscss/_tokens.scss
--bs-transition-base, --bs-transition-fade, --bs-transition-collapseall 200ms …, opacity 120ms linear, height 320ms …; all none under reduced motionscss/_tokens.scss, scss/_brand.scss
--rb-*Raw palette, privatescss/_tokens.scss
--color-*Aliases of --bs-body-bg, --bs-primary, --bs-link-color …scss/_tokens.scss
--font-*, --line-height-*Family aliases, weights 400/500/700, sizes xs–3xl, line heightsscss/_tokens.scss
--space-0 … --space-8Same map as $spacersscss/_tokens.scss
--radius-*, --shadow-*Aliases of --bs-border-radius*, --bs-box-shadow*scss/_tokens.scss
--duration-*, --ease-*120 / 200 / 320 ms, two curvesscss/_tokens.scss
--z-base, --z-dropdown, --z-modal, --z-toast0 / 100 / 205 / 300scss/_tokens.scss

The full mapping with values is on Tokens.

Dark-mode overrides

Besides the usual Bootstrap dark set (body, emphasis, secondary, tertiary, link, border, code, highlight, form-valid/invalid), the theme redeclares these in dark mode because Bootstrap normally leaves them fixed:

[data-bs-theme="dark"] {
  --bs-primary: #d4af37;
  --bs-primary-rgb: 212, 175, 55;
  --bs-focus-ring-color: rgba(212, 175, 55, 0.4);
  --bs-box-shadow: 0 4px 12px rgba(0, 0, 0, 0.5);
  --bs-box-shadow-sm: 0 1px 2px rgba(0, 0, 0, 0.4);
  --bs-box-shadow-lg: 0 4px 12px rgba(0, 0, 0, 0.5);
  --color-accent-fg: #0a1b3d;
}

Anything that reads var(--bs-primary) or rgba(var(--bs-primary-rgb), …) — .bg-primary, .text-primary, .border-primary, .rule-hard, your own CSS — follows automatically. See Color modes.

Component variables

Every Bootstrap component declares its own --bs-{component}-* set on its base class (.btn, .card, .modal, .nav …). The theme does not rename or remove any of them. It changes their values through Sass, so --bs-btn-border-radius is 2px, --bs-card-border-radius is 6px, and so on. Bootstrap's own component pages remain the reference for the names.

Variables the no-JS component layer adds:

VariableOnDefaultPurpose
--bs-scrollspy-offset.scrollspy0pxTop inset for the section view timelines (match a sticky header). Scrollspy
--bs-toast-offset.toast[popover]1remDistance from the viewport edge for a popover toast. Toasts
--bs-toast-delay.toast-autohide5sHow long before the auto-hide fade. Toasts
--bs-tooltip-*[data-bs-toggle="tooltip"]Bootstrap's valuesDeclared on the host element instead of a generated .tooltip. Tooltips

Overriding per component

Set the variable on the element or any ancestor. No Sass, no recompile. This is the right tool for one-off variants.

HTML
<button type="button" class="btn btn-primary">Default primary</button>
<button type="button" class="btn btn-primary" style="--bs-btn-bg: var(--bs-navy-700); --bs-btn-border-color: var(--bs-navy-700); --bs-btn-color: var(--bs-gold-300); --bs-btn-hover-bg: var(--bs-navy-900); --bs-btn-hover-border-color: var(--bs-navy-900); --bs-btn-hover-color: var(--bs-gold-500);">Navy with gold type</button>
<button type="button" class="btn btn-primary" style="--bs-btn-border-radius: var(--bs-border-radius-pill); --bs-btn-padding-x: var(--space-5);">Pill primary</button>
<button class="btn btn-primary"
        style="--bs-btn-bg: var(--bs-navy-700); --bs-btn-color: var(--bs-gold-300);">
  Navy with gold type
</button>

A whole region can retint. Override --bs-primary-rgb on a wrapper and every opacity-aware utility inside (.bg-primary, .text-primary, .border-primary) reads the new value.

Theme gold
--bs-primary-rgb overridden to navy-500
Same, 15 % opacity
HTML
<div class="d-flex gap-3 flex-wrap">
  <div class="p-3 text-bg-primary rounded">Theme gold</div>
  <div class="p-3 rounded" style="--bs-primary-rgb: 30, 58, 110; background: rgba(var(--bs-primary-rgb), 1); color: var(--bs-cream-50);">--bs-primary-rgb overridden to navy-500</div>
  <div class="p-3 rounded" style="--bs-primary-rgb: 30, 58, 110; --bs-bg-opacity: 0.15; background: rgba(var(--bs-primary-rgb), var(--bs-bg-opacity));">Same, 15 % opacity</div>
</div>
Components whose gold is compiled from $primary (.btn-primary, checked checks, active pills …) carry literal hex values in their own variables. Overriding --bs-primary on a region will not retint them; override their component variable (--bs-btn-bg, --bs-nav-pills-link-active-bg …) or recompile with a new $rb-gold-700.

A card with its own look

Main event

Hogan vs. Andre

WrestleMania III · 1987 · Pontiac Silverdome

HTML
<div class="card" style="--bs-card-bg: var(--bs-navy-900); --bs-card-color: var(--bs-cream-100); --bs-card-border-color: var(--bs-gold-700); --bs-card-cap-bg: rgba(212, 175, 55, 0.12); --bs-card-border-radius: var(--bs-border-radius-sm); max-width: 24rem;">
  <div class="card-header text-gold">Main event</div>
  <div class="card-body">
    <h3 class="card-title h5">Hogan vs. Andre</h3>
    <p class="card-text mb-0" style="color: var(--bs-secondary-color)">WrestleMania III · 1987 · Pontiac Silverdome</p>
  </div>
</div>

Six variables, no new class. If the same override recurs, promote it to a class in your own stylesheet, or to a Sass variable if it should be the default everywhere.

Reading variables in your CSS

Prefer the Bootstrap name for new code and the compat name for old code. Both resolve to the same value, in both modes.

.ticket {
  padding: var(--space-4);                    /* compat token, same value as .p-4 */
  color: var(--bs-body-color);
  background: var(--bs-tertiary-bg);
  border: 1px solid var(--bs-border-color);
  border-radius: var(--bs-border-radius-sm);
  box-shadow: var(--bs-box-shadow-sm);
  font-family: var(--bs-font-display);
  transition: var(--bs-transition-base);
}

Every variable above is present on the root in both color modes.