The Dark Mode Conundrum

Dark mode is not easy ... I discussed (and proved) this concept at length back in May 2020 in my quasi-white-paper The Definitive Guide to Dark Mode and Bootstrap 4 (Also on GitHub.) And subsequently also churned the Bootstrap 5 variant (This page!) (Also on GitHub.)

There are huge contentions around how to make "dark mode" available. For example:

  • Toggle button (with all it's JS, persistence issues (GDPR cookie consent??) and the FOUC that goes with it),
  • vs. leverage a pure prefers-color-scheme media query implementation.


  • Does each UI concept have it's own @media (prefers-... line, thus creating a larger-than-needs-to-be CSS (like prefers-reduced-motion does in 5),
  • vs. inject all the @media (prefers-... at the end of the CSS, thus forcing the authors to maintain two sets of SCSS, leading to maintenance nightmares,
  • vs. go with a whole bunch of sibling classes that can be switched with JS, like Tailwind does,
  • vs. go with a known base class that is switched with JS, like Halfmoon does.

I guess it comes down to time ... both to decide on how to do this, and then churn the code, and then test it.

This body of work explores three methods described in the ".. Definitive Guide .." piece:

  1. bootstrap-night - Two independent theme CSS files, auto-loaded, but with JS to offer toggle button and media query awareness,

  2. bootstrap-nightshade - One CSS file, body class driven and with a JS library to offer toggle button,

  3. bootstrap-dark - Pure form (uses the prefers-color-scheme CSS media query) one CSS file that offers auto OS switching dark mode.


  • Dark Themed drop-in replacement for Bootstrap 5
See Example


  • Dark Mode Bootstrap 5 with add-on JS library
See Example


  • Dark Mode drop-in substitute for Bootstrap 5
See Example

There are a few additional techniques that can be used, but these would use the same patterns as above, but with slight variations. For example:

  1. bootstrap-nightfall - A Bootstrap plugin; add it in after the bootstrap.css to make Bootstrap dark.

  2. (b) bootstrap-blackbox New! - The bootstrap-nightshade example shows how one can use a whole-document class to drive the theme, and using the darkmde.js library can further enhance the experience by providing an interactive selection whilst still honoring the prefers-color-scheme media query.

    But using classes comes with its own conundrum. If the choice is to use data attribues, then the bootstrap-blackbox.css file can be used.

  3. (b) bootstrap-unlit - The default bootstrap-dark.css file is set that light if default/author preference, and dark is the optional.

    The bootstrap-unlit.css file gives one the same outcome, but with dark as the default/author preference, and light is the optional.

  4. (c) bootstrap-dark-plugin New! - The bootstrap-dark-plugin.css is essensially the bootstrap-dark.css without the original bootstrap.css. i.e., just the media query and then the dark color scheme.

    This is useful if you want to use the original CSS or even if you want to use an alternative Bootstrap CSS, but also want to dark-mode enable that.

Visit the GitHub repo. for source, compiled CSS, and links to CDN and NPM.