Bootstrap color-mode auto and prefers-color-scheme: resolved theme detection after OS switch

Direct answer

No. Bootstrap 5.3 does not publish a theme-resolved event or callback when data-bs-theme="auto" is active. The only supported surface is the data-bs-theme attribute itself, which the color-mode script writes to the root element on load and on prefers-color-scheme changes.

Confirmed facts

Assumes Bootstrap 5.3.x; internal behavior can vary by patch version.

• Bootstrap 5.3 color-mode initializes on the element carrying data-bs-theme, commonly <html>.
• With auto, it sets document.documentElement.dataset.bsTheme to light or dark using matchMedia('(prefers-color-scheme: dark)').
• It re-applies the attribute when the media query changes.
• No public themeChanged event or subscription API is documented.

Likely explanation and workaround

React to the attribute Bootstrap already sets instead of re-implementing its media-query logic. Attach a MutationObserver to document.documentElement watching attributes with attributeFilter: ['data-bs-theme']. In the callback, read dataset.bsTheme. If the value is auto or absent, resolve it yourself with matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'.

Keep an independent matchMedia change listener only if you must act before Bootstrap updates the DOM. Otherwise both listeners can fire for one OS switch; read the final attribute value after the update to deduplicate.

Nested auto and legacy browsers

Bootstrap documents color-mode behavior for the element it initializes. A descendant data-bs-theme="auto" is not documented to re-resolve independently against the OS preference after an ancestor holds a concrete theme. Treat nested auto as unspecified and use explicit light or dark on independent themed subtrees.

In browsers without CSS custom property support, Sass fallbacks stay static and runtime variable changes do not apply. Prefer explicit themes or server-side selection, then read data-bs-theme or a theme class to synchronize third-party charts and icons.

Verification steps

1. Confirm Bootstrap 5.3.x and <html data-bs-theme="auto">.
2. Open DevTools, toggle the OS color scheme, and inspect document.documentElement.dataset.bsTheme; it should flip between light and dark.
3. Add a MutationObserver log and a matchMedia change log during an OS switch to confirm which fires and whether both fire.

Missing diagnostic detail

Is data-bs-theme="auto" declared on the root <html> element or on a descendant? This determines whether nested auto is expected to re-resolve independently.