Theme Switcher

Component for switching between light, dark, and system themes with persistent preferences

Basic Usage

The most basic theme switcher with dropdown variant (default):

<neura::theme-switcher />

Variants

The theme switcher component supports three variants:

Dropdown (Default)

A dropdown menu with three options: Light, Dark, and System:

<neura::theme-switcher variant="dropdown" />

Stacked

Three buttons stacked horizontally for Light, Dark, and System themes:

<neura::theme-switcher variant="stacked" />

Inline

A simple toggle button that switches between Light and Dark themes:

<neura::theme-switcher variant="inline" />

Custom Icons

Customize the icons used for light, dark, and system themes:

<neura::theme-switcher 
    variant="dropdown" 
    lightIcon="sun" 
    darkIcon="moon" 
    systemIcon="computer-desktop" 
/>

Icon Variant

Control the icon size using the iconVariant prop:

Mini

Micro

Outline

Solid

<neura::theme-switcher iconVariant="mini" />
<neura::theme-switcher iconVariant="micro" />
<neura::theme-switcher iconVariant="outline" />
<neura::theme-switcher iconVariant="solid" />

Theme Modes

The theme switcher supports three modes:

Light Mode

Forces light theme regardless of system preferences.

Dark Mode

Forces dark theme regardless of system preferences.

System Mode

Follows the system's color scheme preference. Automatically switches between light and dark based on the user's OS settings.

Persistence

The theme preference is automatically saved to localStorage and persists across page reloads:

Your theme preference is saved automatically. Refresh the page to see it persist.

Use Cases

Navigation Bar

My Application

Settings Panel

Appearance

Theme

Compact Header

Dashboard

Alpine.js Integration

The theme switcher uses Alpine.js magic property $theme for theme management:

Current theme:

Resolved theme:

<div x-data>
    <p x-text="'Current: ' + $theme.get().stored"></p>
    <button x-on:click="$theme.setLight()">Set Light</button>
    <button x-on:click="$theme.setDark()">Set Dark</button>
    <button x-on:click="$theme.toggle()">Toggle</button>
</div>

Best Practices

Do

Place the theme switcher in an easily accessible location (header/navbar)
Use the dropdown variant for better UX with system mode option
Use the inline variant for minimal UI where space is limited
Provide visual feedback when theme changes
Respect user preferences stored in localStorage

Don't

Hide the theme switcher in hard-to-find locations
Force a specific theme without user control
Forget to handle system theme changes
Use too many different theme switcher variants on the same page

Properties

Property	Type	Default	Description
variant	string	'dropdown'	Theme switcher style: 'dropdown', 'stacked', or 'inline'
lightIcon	string	'sun'	Icon name for light theme
darkIcon	string	'moon'	Icon name for dark theme
systemIcon	string	'computer-desktop'	Icon name for system theme
iconVariant	string	'mini'	Icon size variant: 'mini', 'micro', 'outline', or 'solid'