- Docs
- Configuration options
Configuration options
Every @samline/theme option, data-theme control and script tag attribute, with defaults and how modes, themes and storage are read.
Options
| Option | Default | Description |
|---|---|---|
themes |
['light', 'dark'] |
Themes that can be chosen, besides 'system' |
defaultMode |
'system' |
Mode used when nothing is stored: a theme name or 'system' |
attribute |
'data-theme' |
Attribute that receives the theme name, or 'class' to add it as a class (other theme classes are removed) |
target |
<html> |
Element or selector that receives the theme, for widgets and previews |
storageKey |
'theme' |
localStorage key, or false to not remember the choice |
colorScheme |
true |
Set color-scheme on the target for light and dark, so scrollbars and form controls follow |
themeColor |
none | Browser UI color per theme, such as { light: '#fff', dark: '#111' }, written to <meta name="theme-color"> (created if missing) |
disableTransitions |
true |
Turn CSS transitions off while switching, so the page swaps at once |
controls |
true |
Handle the data-theme-* controls below |
scope |
document |
Where controls are looked for and listened to |
onChange |
none | Called with { mode, theme } on every change |
A stored value that is not a known theme or 'system' is ignored, and defaultMode is used. 'auto' is read as 'system'.
Controls
| Markup | Behavior |
|---|---|
<button data-theme-set="dark"> |
Chooses that mode; gets aria-pressed="true" while it is the mode |
<input type="radio" data-theme-set="dark"> |
Chooses that mode when checked; is checked while it is the mode |
<button data-theme-toggle> |
Switches light and dark; aria-pressed="true" while dark is in effect |
<select data-theme-select> |
Chooses its value; shows the current mode. Give it system and theme options. |
Clicks and changes are delegated from scope, so controls added later work. Every control is synced on each change and once the DOM is ready.
Script tag attributes
For the browser bundle (theme.global.js):
| Attribute | Option |
|---|---|
data-themes="light dark sepia" |
themes (spaces or commas) |
data-default="light" |
defaultMode |
data-attribute="class" |
attribute |
data-storage-key="site-theme" |
storageKey ("false" to not remember) |
data-manual |
Do not start; call Theme.auto(options) |