Theme Switcher

WHEN TO USE

• A product lets the user choose between light and dark, or between brands, and the choice should apply to a region of the page rather than to the document.
• You are demoing or documenting the system and want a visible way to switch brands without reloading.
• You need to react to the change — onThemeSwitcherChange reports the resolved theme, the logo, and whether the change was applied scoped or through the deprecated global path.

WHEN NOT TO USE

• You want the theme applied and never changed by the user. Wrap the region in the theme host and set its attributes directly — the switcher is the UI for changing it, not the mechanism for applying it.USE THEME →
• You need a general-purpose menu of options anchored to a button. The switcher is a specific control with a fixed, data-driven brand list.USE POPOVER →
• The choice is any other binary setting. Nothing here generalises beyond brand and mode.USE TOGGLE →

DO

• Put an <al-theme> ancestor above the switcher. That is the supported path: the switcher walks up to the nearest one and sets its attributes, which scopes the change instead of mutating the document.
• Set scopedOnly when you want the deprecated global stylesheet swap to never run, even if the theme host is missing. It turns a silent fallback into a no-op you can notice.
• Read scoped from the onThemeSwitcherChange detail if you need to know which path ran. It is true when a theme ancestor was found and updated, false when the legacy swap was used.
• Add a brand by adding an entry to the component's brand table rather than by branching in consumer code — the list is data, and the component does not change when it grows.

DON’T

• Don't depend on the global swap. It removes and re-appends a <style id="al-tokens-sheet"> element in the document head, is marked deprecated with a removal target of 3.0.0, and exists only because one in-repo fixture still uses the switcher with no theme wrapper.
• Don't put two switchers over the same theme host expecting them to stay in step. Each one sets attributes on the host; neither reads the other's state.
• Don't assume changing the theme re-renders the whole page cheaply when the page is server-rendered. Each themed host serialises its brand and mode blocks into its own declarative shadow DOM template, which is a real cost when many themed islands are rendered on the server.
• Don't expose a brand switch to end users when the brand is a property of the product rather than a preference. Mode is a preference; brand usually is not.