Description

The ThemeSwitcher component provides a UI control for users to switch between different themes (auto, light, dark). It extends the ShadowComponent class and uses the theme utility internally for state management, persistence, and synchronization.

The component supports two display modes: segmented (shows all options as buttons) and toggle (single button that cycles through options on click). When mode is "auto" (the default), the component detects if it is inside a <k-aside> and switches between segmented and toggle based on the aside state.

Note: You can manage theme state without this component by directly importing the theme utility.

Basic Usage (Segmented)

By default, the component renders as a segmented control with buttons for each theme option. The active theme is highlighted.

<k-theme-switcher></k-theme-switcher>

Toggle Mode

Set mode="toggle" to display a single button that cycles through the theme options on each click.

<k-theme-switcher mode='toggle'></k-theme-switcher>

Custom Options

Use the options attribute to control which themes are available and in what order. Provide a comma-separated list. Both toggle and segmented modes respect this attribute.

<k-theme-switcher options='dark, light'></k-theme-switcher>

<k-theme-switcher mode='toggle' options='dark, light'></k-theme-switcher>

Auto Mode (Aside Detection)

When mode="auto" (the default), the component checks if it is inside a <k-aside>. If so, it renders as segmented when the aside is expanded or offscreen, and as toggle when the aside is collapsed. If the component is not inside an aside, it always renders as segmented.

<k-aside main='push' state='expanded' style='--aside_padding: 0;'>
  <k-aside-toggle>
    <h5 class='m0'>Kempo</h5>
  </k-aside-toggle>
  <k-aside-item icon='cards' href='#' active>Dashboard</k-aside-item>
  <k-aside-item icon='check' href='#'>Tasks</k-aside-item>
  <k-aside-item icon='label' href='#'>Email</k-aside-item>
  <k-aside-spacer></k-aside-spacer>
  <div class='p d-f jc-c'>
    <k-theme-switcher style='--padding: 0.5rem;'></k-theme-switcher>
  </div>
</k-aside>
<k-main>
  <h2>Main Content</h2>
  <p>Toggle the aside to see the ThemeSwitcher switch modes.</p>
</k-main>

Labels

The labels attribute adds text labels next to each icon. Works in both segmented and toggle modes. Labels are automatically hidden when inside a collapsed <k-aside> to preserve space.

• labels (no value) — uses capitalized option names: "Light", "Auto", "Dark"
• labels="Claro, Auto, Oscuro" — uses custom labels in the same order as options

<k-theme-switcher labels></k-theme-switcher>

<k-theme-switcher labels='Claro, Auto, Oscuro'></k-theme-switcher>

<k-theme-switcher mode='toggle' labels></k-theme-switcher>

Custom Padding

You can customize the button padding by setting the --padding CSS custom property. The default padding uses var(--spacer, 1rem).

<k-theme-switcher style="--padding: 0.5rem;"></k-theme-switcher>
<k-theme-switcher style="--padding: 2rem;"></k-theme-switcher>

JavaScript Reference

Constructor

Extends ShadowComponent

new ThemeSwitcher()

Requirements

• ShadowComponent
• Icon
• theme utility

Properties

currentTheme: string

Gets or sets the current theme. Possible values are "auto", "light", or "dark". This property is reactive and will trigger a re-render when changed. Syncs to current-theme attribute.

mode: string

Controls the display mode of the component. Possible values:

• "auto" (default) - Detects if inside a <k-aside>. Shows segmented when aside is expanded/offscreen, toggle when collapsed. If not in an aside, shows segmented.
• "toggle" - Single button that cycles through options on click.
• "segmented" - Shows all options as separate buttons with the active one highlighted.

options: string

A comma-separated list of theme options to display. Defaults to "light, auto, dark". Controls which themes are available and in what order for both toggle and segmented modes. Spaces around commas are optional.

labels: string

A comma-separated list of labels to display next to each icon, matching the order of options. When present with no value (e.g., just labels), defaults to capitalized option names ("Light", "Auto", "Dark"). Labels are automatically hidden when inside a collapsed <k-aside> to preserve space. Works in both segmented and toggle modes.

CSS Custom Properties

--padding: length

Padding of all buttons. Defaults to var(--spacer, 1rem).

--c_inactive: color

Background color of inactive buttons. Defaults to transparent.

--tc_inactive: color

Text/icon color of inactive buttons. Defaults to inherit.

--c_inactive__hover: color

Background color of inactive buttons on hover. Defaults to var(--c_bg__alt).

--tc_inactive__hover: color

Text/icon color of inactive buttons on hover. Defaults to inherit.

--c_active: color

Background color of the active button. Defaults to var(--c_primary).

--tc_active: color

Text/icon color of the active button. Defaults to var(--tc_light).

--c_active__hover: color

Background color of the active button on hover. Defaults to var(--c_active).

--tc_active__hover: color

Text/icon color of the active button on hover. Defaults to var(--tc_active).

--border: border

Border applied to inactive buttons in segmented mode. Defaults to 1px solid var(--c_border).

Example — styling for use on a primary-colored nav background:

k-theme-switcher {
  --padding: 0.5rem;
  --c_inactive: transparent;
  --tc_inactive: var(--tc_light);
  --c_active: white;
  --tc_active: var(--c_primary);
  --border: 1px solid rgba(255, 255, 255, 0.4);
}

Methods

The ThemeSwitcher class does not introduce any new public methods beyond those provided by the ShadowComponent class.

Static Methods

Note: These static methods are convenience wrappers around the theme utility. For direct theme management without the component, use the theme utility directly.

static setTheme(theme): void

Sets the specified theme. Internally calls the theme utility which handles persistence and DOM updates.

• theme string - The theme to set. Must be one of: "auto", "light", or "dark"

// Programmatically set theme to dark mode
ThemeSwitcher.setTheme('dark');

static getCurrentTheme(): string

Gets the current theme. Returns "auto" if no theme is set. Internally calls the theme utility.

// Get the current theme
const currentTheme = ThemeSwitcher.getCurrentTheme();
console.log(currentTheme); // "auto", "light", or "dark"

static getCalculatedCurrentTheme(): string

Returns the effective theme, always "dark" or "light". If the current theme is "auto", this method uses the user's system preference (prefers-color-scheme media query) to determine the theme. Internally calls the theme utility.

// Get the calculated current theme
  const effectiveTheme = ThemeSwitcher.getCalculatedCurrentTheme();
  console.log(effectiveTheme); // "dark" or "light"

Automatic Theme Detection

When the theme is set to "auto", the theme utility automatically detects the user's system preference using prefers-color-scheme media query. The detected theme is applied to the document element as an auto-theme attribute.

The theme utility handles persistence via localStorage and ensures theme changes are reflected in the DOM, providing a consistent user experience.

Related

See the theme utility documentation for programmatic theme management without using this component.