ThemeSwitcher

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.

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

Basic Usage

Use the ThemeSwitcher component to allow users to cycle through themes. Clicking the button cycles through auto → light → dark → auto. The component automatically detects the user's system preference when in auto mode.

<k-theme-switcher></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.

CSS Custom Properties

--padding: length

Controls the padding of the theme switcher button. Defaults to var(--spacer, 1rem). You can override this to customize the button's spacing.

k-theme-switcher {
  --padding: 0.5rem;
}

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.