Skip to content
Tutorials Center
My learning

Topics

Lesson 43 of 58 ยท Customizing

Color Modes and Dark Mode

Use Bootstrap 5.3 color modes: set data-bs-theme on the page or one component, follow prefers-color-scheme and build a light, dark and auto switcher.

Many visitors prefer dark pages, especially at night, and many operating systems tell the browser so. Bootstrap 5.3 has built-in color modes for this. A color mode is a set of CSS variable values (page background, text color, borders, tinted backgrounds, link colors) for either light or dark. You switch the mode with one attribute, data-bs-theme, and every Bootstrap component repaints because they all read those variables. This lesson builds on Customizing with CSS Variables.

One attribute, two modes

Put data-bs-theme on the <html> element to set the mode for the whole page:

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

The two valid values are light and dark. If the attribute is missing, you get light. In the compiled CSS, Bootstrap defines the light values on :root, [data-bs-theme=light] and the dark values on [data-bs-theme=dark]. The dark block redefines variables such as --bs-body-bg (#212529), --bs-body-color (#dee2e6), --bs-border-color, the link colors and all the -bg-subtle, -border-subtle and -text-emphasis tints. It also sets the CSS property color-scheme: dark, so native scrollbars and form widgets switch to their dark rendering.

Nothing is recompiled, and nothing is swapped in the HTML except the one attribute.

Flip the whole page with one attribute

A different mode on one component

Because the mode is just an attribute that cascades, you can put it on any element. The variables are redefined for that element and its descendants, and the nearest ancestor with the attribute wins.

HTML
<div class="card" data-bs-theme="dark"> ... </div>

This gives you a dark card on a light page, a dark footer, a light panel inside a dark page, and so on. It replaces an older habit: in Bootstrap 5.2 you wrote navbar-dark or text-white and hoped the children matched. In 5.3 the preferred navbar markup is:

HTML
<nav class="navbar navbar-expand-lg bg-body-tertiary" data-bs-theme="dark">

The navbar-dark class still works, but it is deprecated in favor of data-bs-theme="dark".

Mixed modes on one page

Write adaptive markup

Color modes only help if your classes follow them. Some Bootstrap classes are fixed: they always mean the same color. Others are adaptive: they read the mode-aware variables.

Fixed (does not change) Adaptive (follows the mode)
bg-white, bg-light, bg-dark bg-body, bg-body-secondary, bg-body-tertiary
text-white, text-black, text-dark text-body, text-body-secondary, text-body-emphasis
border-light, border-dark border (uses --bs-border-color), border-secondary-subtle
text-primary (same blue both ways) text-primary-emphasis, bg-primary-subtle, border-primary-subtle
btn-light, btn-dark btn-outline-secondary, btn-primary (works in both)

A common beginner bug is a light page that is perfect and a dark page where one bg-light box glows like a lamp. When you build for both modes, prefer the adaptive column. Reserve bg-dark and text-white for elements that should look the same in every mode (a hero image overlay, for example).

Fixed versus adaptive classes

Other things that switch for you: btn-close (its icon turns white in dark mode), form controls, tables, list groups, dropdown menus, popovers, and the default link colors.

Following the visitor's preference

Browsers expose the operating-system setting through the CSS media feature prefers-color-scheme, and to JavaScript through window.matchMedia. By default, Bootstrap does not react to it. The default $color-mode-type: data means modes come only from the attribute. That is a deliberate choice, because it lets users override the system setting.

There are two ways to follow the system:

  1. At compile time (Sass). Set $color-mode-type: media-query and Bootstrap generates its dark styles inside @media (prefers-color-scheme: dark). The page is automatically dark when the system is dark, with no script. The price: you can no longer switch it by hand with the attribute.
  2. In JavaScript (the usual choice). Keep the data-attribute mode and set it from the preference. This supports three user choices: Light, Dark and Auto (follow the system).
flowchart TD
  C["User choice"] --> L["light"]
  C --> D["dark"]
  C --> A["auto"]
  A --> Q{"matchMedia<br/>prefers-color-scheme: dark?"}
  Q -->|yes| D2["data-bs-theme = dark"]
  Q -->|no| L2["data-bs-theme = light"]
  L --> L2
  D --> D2

Auto resolves the system preference into light or dark; the attribute only ever holds one of the two.

Notice that auto is never written to the attribute. The attribute accepts light or dark; "auto" is a state in your script.

A theme switcher

Here is a complete switcher with the three choices. It listens for system changes while "Auto" is selected, and marks the active button with aria-pressed so assistive technology knows the state.

In a real site you would remember the choice with localStorage. This site's live editor runs in a sandbox where storage is blocked, so the script below keeps the choice in a variable and wraps the storage calls in try/catch. If storage works, it is used; if it throws, nothing breaks.

Light, Dark and Auto switcher

On your own site, put the "read the saved choice and set the attribute" part in a tiny inline script in the <head>, before the stylesheet. That way the page is dark from the first paint and never flashes white:

HTML
<head>
  <script>
    (function () {
      var saved = null;
      try { saved = localStorage.getItem('theme'); } catch (e) {}
      var dark = window.matchMedia('(prefers-color-scheme: dark)').matches;
      var mode = saved === 'light' || saved === 'dark' ? saved : (dark ? 'dark' : 'light');
      document.documentElement.setAttribute('data-bs-theme', mode);
    })();
  </script>
  <link rel="stylesheet" href="...bootstrap.min.css">
</head>

Your own colors in both modes

For your own CSS, define custom variables once per mode, and use them everywhere. This keeps mode logic in one place:

CSS
:root {
  --site-surface: #ffffff;
  --site-accent: #7c3aed;
}
[data-bs-theme="dark"] {
  --site-surface: #1b1f27;
  --site-accent: #a78bfa;
}
.callout {
  background: var(--site-surface);
  border-left: 4px solid var(--site-accent);
}

The [data-bs-theme="dark"] selector matches any element with the attribute, so your variables also respond when only one component is switched. Images need thought too: a logo with a dark background baked in will not adapt. Use SVG with currentColor, or two images chosen with CSS ([data-bs-theme="dark"] .logo-light { display: none }).

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which attribute switches a Bootstrap 5.3 page to dark mode?

    Bootstrap 5.3 reads data-bs-theme, with the values light and dark, on any element.
  2. 2. You want one dark card on a light page. What do you do?

    The attribute redefines the mode variables for that element and its children, so the card and its text, borders and inputs all adapt.
  3. 3. In dark mode one box stays bright white. What is the likely cause?

    bg-light and bg-white are fixed colors. bg-body, bg-body-secondary and bg-body-tertiary follow the mode.
  4. 4. Does Bootstrap follow prefers-color-scheme by default?

    The default mode type is data. Set it to media-query in Sass, or use matchMedia in a script, to follow the system.
  5. 5. What value should a switcher write to data-bs-theme when the user chose Auto?

    The attribute only knows light and dark. Auto is your script's own state, resolved with matchMedia('(prefers-color-scheme: dark)').

Summary

  • data-bs-theme="light|dark" on <html> sets the color mode; the dark block redefines the --bs-* variables and color-scheme.
  • Put the attribute on any element for a per-component mode; the nearest ancestor wins.
  • Use adaptive classes (bg-body-*, text-body-*, *-subtle, *-emphasis) rather than fixed ones (bg-light, text-dark).
  • Bootstrap does not follow the system setting by default: use matchMedia in JavaScript, or Sass with $color-mode-type: media-query.
  • A switcher offers Light, Dark and Auto, writes only light or dark to the attribute, and keeps its state in storage (guarded with try/catch) or in memory.
  • Define your own colors as variables per mode so your custom CSS follows the theme too.

Next lesson: Building a Custom Theme.