Logo
Neura UI
Loading…
Logo
All pages 86

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):
blade 
<neura::theme-switcher />

Variants

The theme switcher component supports three variants:

Dropdown (Default)

A dropdown menu with three options: Light, Dark, and System:
blade 
<neura::theme-switcher variant="dropdown" />

Stacked

Three buttons stacked horizontally for Light, Dark, and System themes:
blade 
<neura::theme-switcher variant="stacked" />

Inline

A simple toggle button that switches between Light and Dark themes:
blade 
<neura::theme-switcher variant="inline" />

PullCord

A physics-driven hanging cord. Pull the knob to toggle the theme:
blade 
<neura::theme-switcher variant="pullcord" />

Custom Icons

Customize the icons used for light, dark, and system themes:
blade 
<neura::theme-switcher 
    variant="dropdown" 
    lightIcon="sun" 
    darkIcon="moon" 
    systemIcon="computer-desktop" 
/>

Icon Variant

Control the icon size using the iconVariant prop:
blade

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

Switch Animation

Theme changes use the browser View Transition API for a smooth reveal (circle expand by default). Pass animation to pick an effect — unsupported browsers and prefers-reduced-motion fall back to an instant switch.
blade 
<neura::theme-switcher variant="inline" animation="circle" />
<neura::theme-switcher variant="inline" animation="blur-circle" />
<neura::theme-switcher variant="inline" animation="qr-scan" />
<neura::theme-switcher variant="inline" animation="polygon" />
<neura::theme-switcher variant="inline" animation="polygon-gradient" />
<neura::theme-switcher variant="inline" animation="none" />
Configure defaults globally from Alpine, or pass the click event so the circle expands from the control:
Blade 
<div x-data x-init="$theme.configure({ animationType: 'blur-circle', duration: 900 })">
    <button type="button" x-on:click="$theme.toggle($event)">Toggle</button>
</div>

Alpine.js Integration

The theme switcher uses the Alpine.js magic property $theme for theme management. Pass $event so the animation originates from the clicked control:
blade

Stored: · Resolved: 

<div x-data>
    <p>Stored: <span x-text="$theme.stored"></span></p>
    <button x-on:click="$theme.setLight($event)">Set Light</button>
    <button x-on:click="$theme.setDark($event)">Set Dark</button>
    <button x-on:click="$theme.toggle($event)">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
  • Pass $event to theme methods so the reveal expands from the control
  • 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', 'inline', or 'pullcord'
animation string 'circle' View Transition effect: circle, blur-circle, qr-scan, polygon, polygon-gradient, gif, or none
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'