# Local Storage Head (Theme Switcher)
## Usage
The LSH (Local Storage Head) component provides an easy way to manage theme switching and style preferences. It stores selections in `localStorage` under the key `__Z_THEME__` and applies them as classes to the `` element. Multiple instances automatically stay in sync.
To implement LSH, you'll need to make some modifications to your HTML code to allow users to change their preferences.
**1.** Start by setting a default theme and mode in the `` tag of your HTML by checking the user's preference:
```html
```
This will first check if a user previously set the theme color preference manually using `localStorage`, and as a fallback, it will either set dark or light mode based on the browser's color scheme preference.
Note You can replace `z-[group]-[value]` with anything you want as the default.
**2\.** Ensure that your `` tag includes the classes `bg` and `color` to apply the proper background and text colors that automatically adapt to the currently set theme.
```html
```
**3\.** You can now use any instance of `` component anywhere in your HTML.
## Theme toggle
Enable toggle mode to create a button that switches between light and dark modes:
```html
```
When `toggle` is enabled with `group="mode"`, the button automatically switches between light and dark modes, ignoring the `value` attribute.
## Configuration groups
The component supports multiple configuration groups beyond just light/dark mode:
### Mode group (special behavior)
The `mode` group has special handling:
- `value="light"` removes the `dark` class from ``
- `value="dark"` adds the `dark` class to ``
```html
```
### Custom groups
Other groups apply class names directly to the `` element:
```html
```
When switching within a group, the component automatically removes the previous class with **the same** prefix.
## Prevent auto-update
By default, all instances sync when one changes. Use `prevent-autoupdate` to create standalone buttons:
```html
```
## Programmatic control
Listen to events to respond to theme changes:
```html
```
## Local storage structure
The component stores configuration in localStorage under the key `__Z_THEME__`:
```json
{
"mode": "dark",
"color": "z-theme-blue",
"font": "z-font-medium"
}
```
## Internationalization
The LSH component supports internationalization through multiple methods with the following priority order (highest to lowest):
- **Component-level i18n** (via `i18n` attribute or script tag)
- **Global component-specific namespace** (via `
🌓
```
### Available i18n options
| Key | Default | Description |
| ----------------- | -------------------- | ------------------------------------------------------ |
| `aria-label` | Toggle theme | ARIA label for the button |
| `active-label` | Active | Label appended to ARIA when button is active |
| `switch-to-dark` | Switch to dark mode | ARIA description when switching to dark (toggle mode) |
| `switch-to-light` | Switch to light mode | ARIA description when switching to light (toggle mode) |
## Custom classes
The LSH component supports custom CSS classes through the `cls` attribute.
### Using simple string format
```html
```
### Using JSON object format
```html
```
### Available cls target
| Target | Description |
| -------- | ------------------ |
| `button` | The button element |
## Custom inline styles
The LSH component supports custom inline styles through the `stl` attribute.
### Example
```html
```
## Attributes
| Name | Type | Default | Description |
| ------------------------ | ------- | ------- | ----------------------------------------------------------------------- |
| `value` | String | | The specific theme value to apply (e.g., "dark", "z-theme-blue") |
| `group` | String | | Configuration group (e.g., "mode", "color", "font") |
| `toggle` | Boolean | false | Enables toggle behavior for mode switching (ignores value attribute) |
| `prevent-autoupdate` | Boolean | false | Prevents this instance from syncing with other instances |
| `cls` | String | | Custom CSS classes for the button |
| `stl` | String | | Custom inline styles for the button |
| `i18n` | String | | Internationalization strings as JSON object or via configuration script |
| `force-prevent-rerender` | Boolean | false | Prevents component rerendering (useful for HTMX or SPA scenarios) |
## Events
| Name | Description |
| ---------------------- | ------------------------------------------------------------------------------------------------------ |
| `z-lsh:before-change` | Fired before theme change (cancelable). Event detail contains `{group, value, previousValue, config}`. |
| `z-lsh:change` | Fired after theme change. Event detail contains `{group, value, previousValue, config}`. |