Persist theme and style preferences to localStorage and sync with document classes.
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 __FRANKEN__ and applies them as classes to the <html> 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 <head> tag of your HTML by checking the user’s preference:
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 uk-[group]-[value] with anything you want as the default.
2. If you are using Frankenstyle, ensure that your <body> tag includes the classes bg and color to apply the proper background and text colors that automatically adapt to the currently set theme.
Note If you are using a different CSS framework, such as Tailwind CSS, ensure that you implement your own background and foreground colors.
3. You can now use any instance of <uk-lsh> component anywhere in your HTML.
Enable toggle mode to create a button that switches between light and dark modes:
When toggle is enabled with group="mode", the button automatically switches between light and dark modes, ignoring the value attribute.
The component supports multiple configuration groups beyond just light/dark mode:
The mode group has special handling:
value="light" removes the dark class from <html>value="dark" adds the dark class to <html>Other groups apply class names directly to the <html> element:
When switching within a group, the component automatically removes the previous class with the same prefix.
By default, all instances sync when one changes. Use prevent-autoupdate to create standalone buttons:
Listen to events to respond to theme changes:
The component stores configuration in localStorage under the key __FRANKEN__:
The LSH component supports internationalization through multiple methods with the following priority order (highest to lowest):
i18n attribute or script tag)<script id="uk-i18n">)| 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) |
The LSH component supports custom CSS classes through the cls attribute.
| Target | Description |
|---|---|
button | The button element |
The LSH component supports custom inline styles through the stl attribute.
| Name | Type | Default | Description |
|---|---|---|---|
value | String | The specific theme value to apply (e.g., “dark”, “uk-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) |
| Name | Description |
|---|---|
uk-lsh:before-change | Fired before theme change (cancelable). Event detail contains {group, value, previousValue, config}. |
uk-lsh:change | Fired after theme change. Event detail contains {group, value, previousValue, config}. |