EN | FR
A modern solution to offer a light/dark theme selector and enhance the user experience across all your web interfaces.
BrowserUX Theme Switcher is a lightweight, accessible, and customizable Web Component designed to easily add a theme switcher button to any website or application. It automatically detects the system theme, remembers the user's preference, and applies the correct theme.
- 🎚 Toggles
data-theme="light"/"dark"on<html>or a custom target element - 💾 Persists user preference in
localStorage - 🕶 Detects system preference via
prefers-color-schemeon first load - 📢 Dispatches a
theme-changecustom event on every theme change - 🧠 Dynamic ARIA labels, multilingual, auto-detected or customizable
- 🌐 Built-in i18n for 9 languages (
en,fr,es,de,ja,ru,pt,it,nl) - 🖼 Automatic image swapping via filename convention or explicit
data-src-*attributes - 🎨 Fully customizable via CSS custom properties (
--bux-switch-*) - 🧩 Optional Shadow DOM, disable with
no-shadow
npm install browserux-theme-switcherOr via CDN:
<script type="module" src="https://unpkg.com/browserux-theme-switcher/dist/browserux-theme-switcher.esm.js"></script>import 'browserux-theme-switcher';<browserux-theme-switcher></browserux-theme-switcher>| Parameter | Type | Description |
|---|---|---|
target |
Attribute | CSS selector for the element that receives data-theme |
lang |
Attribute | Language code for built-in ARIA labels |
data-label-light |
Attribute | Custom ARIA label for activating light mode |
data-label-dark |
Attribute | Custom ARIA label for activating dark mode |
no-shadow |
Attribute | Disable Shadow DOM encapsulation |
style |
Attribute | CSS custom properties for visual customization |
theme-change |
Event | Fired on every theme change, e.detail.theme is "light" or "dark" |
light-icon |
Slot | Icon displayed on the light side of the toggle |
dark-icon |
Slot | Icon displayed on the dark side of the toggle |
For detailed documentation, see docs/index.md.
- Introduction : what it is, why it exists, the three-step logic
- Getting started : installation via npm or CDN, adding CSS
- How it works : lifecycle, persistence, Shadow DOM, ARIA
- Framework usage : React, Vue, Angular, vanilla JS
- Theming : CSS variables, image switching strategies
- Attributes :
target,lang,data-label-*,no-shadow,style - Events :
theme-changeevent with payload and use cases - Slots :
light-icon,dark-iconnamed slots - Utilities :
updateImagesByTheme,updateThemeImages
- Compatibility : browser support, framework compatibility, build formats
- Contributing : report a bug, suggest an improvement, submit a PR
MIT © 2026 Effeilo