Skip to main content

Customize

Color modes

Light and dark ship together. The page follows the OS unless you pin it, and any element can switch on its own.

How it works

Stock Bootstrap only switches modes when something sets data-bs-theme="dark". rb-bootstrap overrides the color-mode() mixin so every dark block is emitted twice: once for the attribute, once inside @media (prefers-color-scheme: dark) for a root that has not been pinned light.

/* explicit */
[data-bs-theme="dark"] { --bs-body-bg: #0a1b3d; … }

/* automatic */
@media (prefers-color-scheme: dark) {
  :root:not([data-bs-theme="light"]) { --bs-body-bg: #0a1b3d; … }
}

So there are three ways to end up dark, and one way to opt out.

MarkupResult
<html> (no attribute)Follows the OS. Light by default, dark when the OS is dark.
<html data-bs-theme="dark">Always dark.
<html data-bs-theme="light">Always light. The media query is ignored.
<div data-bs-theme="dark"> / "light"That subtree switches, whatever the page is doing.

Add <meta name="color-scheme" content="light dark"> so native form controls and scrollbars follow too. Bootstrap also sets color-scheme: dark on the dark root.

What swaps in dark

Light mode is a Sunday-afternoon program: cream paper, navy ink, gold trim. Dark mode is arena lights down, spotlight up: deep navy, and the gold steps up a stop to stay bright.

VariableLightDark
--bs-primary / --bs-primary-rgbgold-700 #b8941fgold-500 #d4af37
--bs-body-bgcream-100 #f4ecd8navy-900 #0a1b3d
--bs-body-colornavy-900 #0a1b3dcream-100 #f4ecd8
--bs-emphasis-color#000cream-50 #faf3df
--bs-secondary-bgcream-300 #d9cdb0#0e2048
--bs-secondary-colornavy-400 #4a6398navy-100 #c8d2e6
--bs-tertiary-bgcream-50 #faf3dfnavy-700 #122553
--bs-tertiary-colornavy-900 at 50 %cream-100 at 50 %
--bs-link-color → --bs-link-hover-colornavy-700 → gold-700gold-300 → gold-500
--bs-border-colorcream-300 #d9cdb0navy-500 #1e3a6e
--bs-border-color-translucentnavy-900 at 17.5 %cream-100 at 15 %
--bs-focus-ring-colorgold-700 at 40 %gold-500 at 40 %
--bs-box-shadow / -sm / -lgNavy-tintedBlack, heavier
--bs-code-color#8b2c45#e2909c
--bs-highlight-bg (mark)gold-300gold-500
--bs-*-text-emphasis, -bg-subtle, -border-subtleDark text on pale tintPale text on deep tint
--bs-form-valid-color / -invalid-colorgreen-600 / red-600#8fd092 / #f0a19a

--bs-primary is the one Bootstrap does not normally change between modes. The theme swaps it in scss/_tokens.scss, and re-emits the components whose gold is baked in at compile time: .btn-primary, .btn-outline-primary, checked checks and radios, the range thumb, active pills, pagination, list-group items, dropdown items, the progress bar and the accordion's open state.

Explicit regions

A dark card on a light page, or the reverse. Everything inside inherits: text, borders, links, forms, alerts, the primary gold.

data-bs-theme="dark"

Body text on navy-900. Links go gold-300.

Primary alert: gold-300 on deep gold.

data-bs-theme="light"

Body text on cream-100. Links go navy-700.

Primary alert: dark gold on pale gold.
HTML
<div class="row g-4">
  <div class="col-md-6">
    <div data-bs-theme="dark" class="p-4 bg-body text-body rounded border">
      <p class="h3">data-bs-theme="dark"</p>
      <p>Body text on navy-900. <a href="#cm-dark-anchor" id="cm-dark-anchor">Links go gold-300</a>.</p>
      <button type="button" class="btn btn-primary">Primary is gold-500</button>
      <button type="button" class="btn btn-outline-secondary">Secondary</button>
      <div class="mt-3">
        <label class="form-label" for="cm-dark-input">Wrestler</label>
        <input type="text" class="form-control" id="cm-dark-input" placeholder="Ravishing Rick Rude" />
      </div>
      <div class="form-check mt-2">
        <input class="form-check-input" type="checkbox" id="cm-dark-check" checked />
        <label class="form-check-label" for="cm-dark-check">Checked check is gold-500</label>
      </div>
      <div class="alert alert-primary mt-3 mb-0">Primary alert: gold-300 on deep gold.</div>
    </div>
  </div>
  <div class="col-md-6">
    <div data-bs-theme="light" class="p-4 bg-body text-body rounded border">
      <p class="h3">data-bs-theme="light"</p>
      <p>Body text on cream-100. <a href="#cm-light-anchor" id="cm-light-anchor">Links go navy-700</a>.</p>
      <button type="button" class="btn btn-primary">Primary is gold-700</button>
      <button type="button" class="btn btn-outline-secondary">Secondary</button>
      <div class="mt-3">
        <label class="form-label" for="cm-light-input">Wrestler</label>
        <input type="text" class="form-control" id="cm-light-input" placeholder="Ravishing Rick Rude" />
      </div>
      <div class="form-check mt-2">
        <input class="form-check-input" type="checkbox" id="cm-light-check" checked />
        <label class="form-check-label" for="cm-light-check">Checked check is gold-700</label>
      </div>
      <div class="alert alert-primary mt-3 mb-0">Primary alert: dark gold on pale gold.</div>
    </div>
  </div>
</div>

The region needs its own background. data-bs-theme changes the variables, not the paint; add .bg-body (or any background utility) and .text-body so the box actually renders in its mode.

Cards and navigation

Main event

Steel cage

The card picks up --bs-card-bg from the dark body background.

Main event

Steel cage

Same markup, pinned light.

HTML
<div class="row g-4">
  <div class="col-md-6">
    <div class="card" data-bs-theme="dark">
      <div class="card-header">Main event</div>
      <div class="card-body">
        <h3 class="card-title h5">Steel cage</h3>
        <p class="card-text">The card picks up <code>--bs-card-bg</code> from the dark body background.</p>
        <ul class="nav nav-pills">
          <li class="nav-item"><a class="nav-link active" aria-current="page" href="#cm-pill-a" id="cm-pill-a">Active</a></li>
          <li class="nav-item"><a class="nav-link" href="#cm-pill-b" id="cm-pill-b">Results</a></li>
        </ul>
      </div>
    </div>
  </div>
  <div class="col-md-6">
    <div class="card" data-bs-theme="light">
      <div class="card-header">Main event</div>
      <div class="card-body">
        <h3 class="card-title h5">Steel cage</h3>
        <p class="card-text">Same markup, pinned light.</p>
        <ul class="nav nav-pills">
          <li class="nav-item"><a class="nav-link active" aria-current="page" href="#cm-pill-c" id="cm-pill-c">Active</a></li>
          <li class="nav-item"><a class="nav-link" href="#cm-pill-d" id="cm-pill-d">Results</a></li>
        </ul>
      </div>
    </div>
  </div>
</div>

Components with a transparent background (cards, alerts, list groups) carry their own color and do not need .bg-body.

A toggle without JavaScript

The theme reads a radio group anywhere in the document. Give the inputs the class color-mode-check and the values auto, light and dark; the root rules use :has() to force the mode. The docs navbar carries one of these.

  • auto (or no toggle at all) follows prefers-color-scheme.
  • light suppresses the automatic dark rules even when the OS is dark.
  • dark applies the dark rules even when the OS is light.
  • An explicit data-bs-theme on the <html> element still wins for light; nested regions keep working as before.
No script means no storage. The choice lasts for the current page and resets on navigation; the browser may restore it on back/forward. If you need persistence, that is the one place a few lines of script are justified: read a cookie or localStorage and set data-bs-theme before first paint.
Color mode
HTML
<fieldset class="color-mode-toggle btn-group">
  <legend class="visually-hidden">Color mode</legend>
  <input type="radio" class="btn-check color-mode-check" name="color-modes-demo" value="auto" id="color-modes-demo-auto" autocomplete="off" checked>
  <label class="btn btn-outline-primary" for="color-modes-demo-auto">Auto</label>
  <input type="radio" class="btn-check color-mode-check" name="color-modes-demo" value="light" id="color-modes-demo-light" autocomplete="off">
  <label class="btn btn-outline-primary" for="color-modes-demo-light">Light</label>
  <input type="radio" class="btn-check color-mode-check" name="color-modes-demo" value="dark" id="color-modes-demo-dark" autocomplete="off">
  <label class="btn btn-outline-primary" for="color-modes-demo-dark">Dark</label>
</fieldset>
Two toggles on one page (this demo and the navbar) are both read: a dark selection in either forces dark, and a light selection in either suppresses auto-dark. Keep one per page in real use.

The selectors the theme emits, from scss/_mixins.scss:

[data-bs-theme="dark"],
:root:has(.color-mode-check[value="dark"]:checked) { /* dark variables */ }

@media (prefers-color-scheme: dark) {
  :root:not([data-bs-theme="light"]):not(:has(.color-mode-check[value="light"]:checked)) { /* dark variables */ }
}

Pinning the whole page

<!-- Always light, whatever the OS says -->
<html lang="en" data-bs-theme="light">

<!-- Always dark -->
<html lang="en" data-bs-theme="dark">

<!-- A dark navbar on an otherwise automatic page -->
<nav class="navbar navbar-expand-lg" data-bs-theme="dark">…</nav>

Pin on <html>, not <body>. The automatic rules target :root:not([data-bs-theme="light"]), so only the root attribute can switch them off.

Limitations

Variables cascade, so a nested region is almost always right. A handful of dark-mode rules are written as descendant selectors rather than variables, and in automatic dark mode they compile to :root:not([data-bs-theme="light"]) .thing. That selector still matches a .thing inside a nested data-bs-theme="light" region, so those parts stay dark:

  • The accordion chevron (--bs-accordion-btn-icon) and its active color.
  • The navbar toggler icon, the select arrow, the unchecked switch dot, the carousel control filter.
  • The theme's own re-emitted primaries: .btn-primary, .btn-outline-primary, checked checks, the range thumb, active pills, pagination, list-group and dropdown items, the progress bar.

The reverse works: a data-bs-theme="dark" region inside a light page is fully correct, because the explicit [data-bs-theme="dark"] .thing selector exists. If you need a light island inside an automatically dark page, pin the root light and mark the dark parts explicitly instead.

The light example above is correct when this page is light, or when the page is dark by attribute. If your OS is dark and the docs are following it, its primary button renders gold-500 instead of gold-700. That is the limitation in action.

Sass

The mixin lives in scss/_mixins.scss and is loaded after Bootstrap's, so it also wraps Bootstrap's own dark blocks (accordion, carousel, close button, navbar, form check and select).

@mixin color-mode($mode: light, $root: false) {
  @if $mode == dark {
    [data-bs-theme="dark"] { @content; }

    @media (prefers-color-scheme: dark) {
      :root:not([data-bs-theme="light"]) { @content; }
    }
  } @else {
    [data-bs-theme="#{$mode}"] { @content; }
  }
}

Use it for your own dark styles so they pick up both triggers.

.ticket-stub {
  background: var(--bs-tertiary-bg);
}

@include color-mode(dark) {
  .ticket-stub {
    background-image: url("stub-dark.svg");
  }
}

Dark values are set in scss/_variables-dark.scss ($body-bg-dark, $link-color-dark, …) and the extra theme colors' dark variants in scss/_maps.scss. See Sass and Color.