bootstrap-dark-theme

Adds a Bootstrap 5 light/dark theme toggle button in the navbar using Bootstrap color mode

Installation

Install via npm:

npm install bootstrap-dark-theme@1

Use locally:

<script src="./node_modules/bootstrap-dark-theme/dist/dark-theme.js"></script>

Use via CDN:

<script src="https://cdn.jsdelivr.net/npm/bootstrap-dark-theme@1"></script>

Usage

Add a <div class="bootstrap-dark-theme"></div> inside your navbar. The dark theme toggle replaces it.

<link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.6/dist/css/bootstrap.min.css" rel="stylesheet" />

<nav class="navbar navbar-expand-lg bg-body-tertiary">
  <div class="container-fluid">
    <a class="navbar-brand" href="#">Navbar</a>
    <div class="bootstrap-dark-theme"></div>
  </div>
</nav>

<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.6/dist/js/bootstrap.bundle.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap-dark-theme@1/dist/dark-theme.js" type="module"></script>

Custom Styling

You can replace <div class="bootstrap-theme"></div> with your toggle. For example:

<div class="position-relative" role="group" aria-label="Toggle dark mode" title="Toggle Dark Mode">
  <button class="dark-theme-toggle btn btn-primary dropdown-toggle" type="button" data-bs-toggle="dropdown" aria-expanded="false" aria-label="Open navigation menu">
    <i class="bi bi-circle-half"></i>
  </button>
  <ul class="dropdown-menu dropdown-menu-end">
    <li><button class="dropdown-item" data-bs-theme-value="light"><i class="me-2 bi sun-fill"></i> Light</button></li>
    <li><button class="dropdown-item" data-bs-theme-value="dark"><i class="me-2 bi bi-moon-stars-fill"> Dark</button></li>
    <li><button class="dropdown-item" data-bs-theme-value="auto"><i class="me-2 bi bi-circle-half"> Auto</button></li>
  </ul>
</div>

Make sure you have:

1. A button with the class dark-theme-toggle that serves as the main toggle button
2. Buttons with the attribute data-bs-theme-value with values:
   • light: Forces the light theme regardless of system preference
   • dark: Forces the dark theme regardless of system preference
   • auto: Uses the system preference (light or dark) based on the user's OS settings
   • Any invalid theme value will default to the same behavior as auto.

How it works:

1. The script looks for elements with the data-bs-theme-value attribute
2. When a user clicks on one of these elements, the script:
   • Validates the theme value (defaulting to auto if invalid)
   • Stores the selected theme in localStorage
   • Applies the theme to the document by setting the data-bs-theme attribute on the root element
   • Updates the UI to show which theme is currently active
3. On page load, the script automatically applies the previously selected theme from localStorage, or if none exists, uses the system preference

Release notes

• 1.2.1: 24 Jun 2025. Enable default file: https://cdn.jsdelivr.net/npm/bootstrap-dark-theme@1
• 1.2.0: 24 Jun 2025. Embed HTML via <div class="bootstrap-theme"></div>
• 1.1.0: 29 May 2025. Treat unknown themes as 'auto'. Add tests
• 1.0.0: 28 May 2025. Initial release

Setup

To run this project locally:

• Clone this repo, and run npm install to install dependencies
• Run npm run build to compile
• Open index.html using a HTTP server (e.g. python -m http.server)

To release, run:

npm version minor
npm publish
git push --tags

License

MIT