# Theme Toggle > Dark/light mode toggle with localStorage persistence Source: https://shellui.dev/docs/v0.3/components/interactive/theme-toggle The ThemeToggle component provides a single-click toggle between dark and light modes. It persists the user's preference to `localStorage` and respects the system color scheme on first visit. ## Installation ```bash shellui add theme-toggle ``` ## Basic Usage Drop it anywhere in your layout: ```razor ``` That's it — the component handles theme switching, persistence, and system preference detection automatically. ## In a Navbar A common placement for the theme toggle: ```razor MyApp ``` ## In a Settings Page Include the toggle in a settings form: ```razor Appearance Customize how the app looks.

Dark Mode

Toggle between light and dark themes.

``` ## How It Works 1. **First visit**: Reads `prefers-color-scheme` from the browser 2. **Toggle**: Adds/removes the `dark` class on `` 3. **Persistence**: Saves the preference to `localStorage` under key `theme` 4. **Hydration**: On page load, applies the saved theme before first paint to prevent flash ## Theme Setup Ensure your `App.razor` or `_Host.cshtml` includes the theme initialization script: ```html ``` ## API Reference | Property | Type | Default | Description | |----------|------|---------|-------------| | — | — | — | No parameters required | The ThemeToggle is a self-contained component with no required parameters. It renders as an icon button that toggles between sun and moon icons. ## Accessibility The ThemeToggle component includes: - `aria-label` describing the current action ("Switch to dark mode" / "Switch to light mode") - Keyboard activatable via Enter and Space - Visible focus ring - Icon transition animation with `prefers-reduced-motion` support