# Theme Toggle
> Dark/light mode toggle with localStorage persistence
Source: https://shellui.dev/docs/v0.4/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
AppearanceCustomize 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