SutraUI.ThemeSwitcher (Sutra UI v0.4.0)

View Source

A component that allows users to toggle between light and dark themes.

The theme switcher dispatches sutra-ui:set-theme events. With the recommended root-layout listener, theme preference is persisted in localStorage and system preference is used as the initial fallback.

Theme Management

The theme switcher integrates with a theme system that:

  • Persists theme preference in localStorage (key: 'sutra-ui:theme')
  • Applies theme before page load to prevent flash of unstyled content
  • Respects system preferences (prefers-color-scheme) as fallback

The component dispatches sutra-ui:set-theme events to integrate with this system.

Examples

# Basic theme switcher
<.theme_switcher id="theme-toggle" />

# With custom tooltip
<.theme_switcher id="theme-toggle" tooltip="Switch theme" />

# With custom tooltip position
<.theme_switcher id="theme-toggle" tooltip="Switch theme" tooltip_side="left" />

# Different button variants
<.theme_switcher id="theme-toggle" variant="ghost" />
<.theme_switcher id="theme-toggle" size="sm" />

# Different icon size
<.theme_switcher id="theme-toggle" icon_class="size-5" />

# Custom classes
<.theme_switcher id="theme-toggle" class="ml-auto" />

Theme Initialization

Add this script to your root layout's <head> to prevent flash of unstyled content:

<script>
  (function() {
    const theme = localStorage.getItem('sutra-ui:theme') ||
      (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
    if (theme === 'dark') document.documentElement.classList.add('dark');

    window.addEventListener('sutra-ui:set-theme', (e) => {
      const newTheme = e.detail?.theme;
      if (newTheme === 'dark') {
        document.documentElement.classList.add('dark');
      } else {
        document.documentElement.classList.remove('dark');
      }
      localStorage.setItem('sutra-ui:theme', newTheme);
    });
  })();
</script>

Summary

Functions

theme_switcher(assigns)

Renders a theme switcher button.

Functions

theme_switcher(assigns)

Renders a theme switcher button.

The button displays a sun icon in dark mode and a moon icon in light mode. Clicking the button toggles between themes.

Attributes

  • id (required) - Unique identifier for the theme switcher. Required for the JavaScript hook.
  • variant - Button variant: "primary", "secondary", "destructive", "outline", "ghost", "link". Defaults to "outline".
  • size - Button size: "default", "sm", "lg", "icon". Defaults to "icon".
  • tooltip - Optional tooltip text shown on hover. The button's aria-label falls back to "Toggle theme" when no tooltip is provided.
  • tooltip_side - Tooltip position: "top", "bottom", "left", "right". Defaults to "bottom".
  • icon_class - CSS class for icon sizing (e.g., "size-4", "size-5"). Defaults to "size-4".
  • class - Additional CSS classes to apply to the button.
  • rest - Additional HTML attributes passed to the button element.

Attributes

  • id (:string) (required) - Unique identifier (required for JavaScript hook).
  • variant (:string) - The visual variant of the button. Defaults to "outline". Must be one of "primary", "secondary", "destructive", "outline", "ghost", or "link".
  • size (:string) - The size variant of the button. Defaults to "icon". Must be one of "default", "sm", "lg", or "icon".
  • tooltip (:string) - Optional tooltip text displayed on hover. Defaults to nil.
  • tooltip_side (:string) - Position of the tooltip relative to the button. Defaults to "bottom". Must be one of "top", "bottom", "left", or "right".
  • icon_class (:string) - CSS class for icon sizing (e.g., size-4, size-5). Defaults to "size-4".
  • class (:string) - Additional CSS classes. Defaults to nil.
  • Global attributes are accepted. Additional HTML attributes. Supports all globals plus: ["aria-label"].