Add Bootstrap 5.3 color mode (data-bs-theme) support#435
Open
dereuromark wants to merge 6 commits into
Open
Conversation
A new ColorModeHelper provides the two pieces that have been
missing for color-mode adoption since the BS5.3 migration:
- `script()` emits an inline IIFE that reads the user's stored
preference from localStorage (falling back to the OS preference
for `auto`), applies `data-bs-theme` to the configured target
(default `<html>`), re-resolves on `prefers-color-scheme`
changes while in auto mode, and exposes a tiny public API
(`window.BootstrapUIColorMode.{get,set}` plus a
`bs-theme-changed` DOM event). Placed in `<head>` it prevents
the flash of unstyled theme.
- `toggle()` renders a Bootstrap button group with one button per
configured mode. Clicks call `BootstrapUIColorMode.set()`,
update the active state, and announce the change via the event.
Configurable: storageKey, default, target, modes, labels (i18n
hook via `__()`), ariaLabel, wrapperClass, buttonClass,
activeClass.
The helper is auto-loaded by `UIViewTrait` as `$this->ColorMode`.
README has a new "Color modes" section under Usage.
Tests cover default and custom-config rendering for both methods
and verify user-supplied labels are HTML-escaped.
ADmad
reviewed
May 11, 2026
Per review: extract the three string constants (MODE_LIGHT, MODE_DARK, MODE_AUTO) into a BootstrapUI\View\Helper\ColorMode enum. The helper's `default` and `modes` config keys now accept either enum cases or plain strings interchangeably, so existing apps that pass `'light'` / `'dark'` / `'auto'` keep working while new code can use the typed API. A small `_modeValue()` helper coerces a value to its string form for places that render or serialize. Updates the README example to use the enum and notes that strings are still accepted. Adds tests covering enum usage on both `modes` and `default`.
Member
Author
|
Addressed in 2112231. Extracted the three string constants into a use BootstrapUI\View\Helper\ColorMode;
echo $this->ColorMode->toggle([
'modes' => [ColorMode::Light, ColorMode::Dark],
'default' => ColorMode::Dark,
]);A small |
ADmad
reviewed
May 11, 2026
ColorMode now implements Cake's EnumLabelInterface and provides its own translated label() — matches FormHelper's enum-label convention and removes the now-redundant 'labels' config on the helper. Custom string modes still fall back to ucfirst().
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds Bootstrap 5.3 color mode (
data-bs-theme) support — the flagship BS5.3 feature that the plugin currently has zero coverage for (agrep -rn 'data-bs-theme\|color-mode' src/ templates/ webroot/againstmasterreturns nothing).The new
ColorModeHelperprovides the two pieces an app needs to actually use color modes without writing custom JS:$this->ColorMode->script()— applies the stored theme on page loadEmits a small inline IIFE that:
localStorage(default key:bs-theme),autoagainstwindow.matchMedia('(prefers-color-scheme: dark)'),data-bs-themeon the configured target (default:<html>),automode,window.BootstrapUIColorMode.{get, set}(mode)for app code,bs-theme-changedDOM event whenever the resolved theme changes.Placed near the top of
<head>, it prevents the flash of unstyled theme that every other "add dark mode in the layout" approach has.$this->ColorMode->toggle()— ready-made switcher widgetRenders a Bootstrap
btn-groupwith one button per configured mode (default: light / dark / auto). Clicking a button callsBootstrapUIColorMode.set(), togglesaria-pressedand the active class, and fires the event. ARIA-labelled, escapes user-supplied labels.Usage
Config knobs (per-call or via
loadHelper):storageKey,default,target,modes,labels,ariaLabel,wrapperClass,buttonClass,activeClass. Labels go through__()if you pass them through; the helper itself escapes them.Wiring
src/View/Helper/ColorModeHelper.phpUIViewTraitas$this->ColorMode.@propertyadded toUIViewdocblock.Notes
bg-light/text-darkin places; those are not touched here. A follow-up could audittemplates/layout/examples/*andFlashHelper.phpfor hardcoded neutrals if you want full dark-mode parity in the bundled layouts.