Bootstrap 5 Dark Mode Toggle
A Dark Mode Toggle is a UI control — typically a checkbox-based switch or button — that allows users to switch between light and dark color schemes on a webpage. In Bootstrap 5, it works by toggling the `data-bs-theme` attribute on the `<html>` or a parent element, which activates Bootstrap's built-in dark theme variables. Use it whenever your site targets users in low-light environments, creative tools, developer dashboards, or any context where eye comfort and aesthetic preference matter.
Primary Class
.dark-mode-toggleCommon Use Cases
- →SaaS dashboards where developers or analysts work long hours and prefer dark interfaces to reduce eye strain during late-night sessions
- →Portfolio sites for designers and developers where dark mode signals technical credibility and matches the aesthetic expectations of the industry
- →Documentation portals (like component libraries or API references) where users spend extended periods reading code snippets and prose
- →E-commerce storefronts that want to offer a premium, personalized experience by persisting the user's theme preference in localStorage across sessions
Variants & Classes
| Variant | Description |
|---|---|
| Dark Mode Toggle Default | Standard dark mode toggle with Bootstrap's default styling. |
| Dark Mode Toggle Responsive | Responsive variant that adapts to different screen sizes. |
Code Example
<div class="d-flex align-items-center gap-2">
<span id="theme-label" class="form-label mb-0 text-body">Dark Mode</span>
<div class="form-check form-switch mb-0">
<input
class="form-check-input"
type="checkbox"
role="switch"
id="darkModeToggle"
aria-labelledby="theme-label"
/>
</div>
</div>
<script>
const toggle = document.getElementById('darkModeToggle');
const root = document.documentElement;
// Load saved preference
const saved = localStorage.getItem('theme');
if (saved === 'dark') {
root.setAttribute('data-bs-theme', 'dark');
toggle.checked = true;
}
toggle.addEventListener('change', () => {
if (toggle.checked) {
root.setAttribute('data-bs-theme', 'dark');
localStorage.setItem('theme', 'dark');
} else {
root.setAttribute('data-bs-theme', 'light');
localStorage.setItem('theme', 'light');
}
});
</script>Live Examples
Basic Dark Mode Toggle
Canvas Framework Variants
The Canvas template extends Bootstrap 5 with 1,658+ component variants. Generate any of these using Canvas Builder:
- ✓Canvas Builder generated dark mode toggle with custom colours
- ✓Dark Mode Toggle with interactive states
- ✓Responsive dark mode toggle for all screen sizes
Best Practices
Set the theme on <html>, not <body>
Apply `data-bs-theme="dark"` to `document.documentElement` (the `<html>` element) rather than `<body>` — this ensures Bootstrap's CSS variables cascade correctly to all components including modals and dropdowns that render outside the body flow.
Respect the OS preference on first load
Before reading localStorage, check `window.matchMedia('(prefers-color-scheme: dark)').matches` as a fallback — this way users get the correct theme immediately without a flash of the wrong mode on their first visit.
Avoid a flash of unstyled theme (FOUT)
Place your theme-detection script in a `<script>` tag directly inside `<head>` — not deferred or async — so the `data-bs-theme` attribute is set before the browser paints, preventing a visible flicker between light and dark.
Use Bootstrap's color-mode utility classes for fine-grained control
Bootstrap 5.3+ introduces `data-bs-theme` at the component level, so you can pin specific cards or sidebars to `data-bs-theme="dark"` regardless of the global setting — useful for sticky navbars that need to stay dark even in light mode.