Color Mode
Dark mode is one attribute on the html element:
data-leverui-color-mode="dark". A short script sets it before the page
paints. createColorMode reads and changes it from your components.
import {
ColorModeButton,
ColorModeScript,
createColorMode,
createColorModeValue,
DarkMode,
getColorModeScript,
LightMode,
} from '@leverui/components';
No provider and no extra library. Without the attribute, the page is light.
Setup
The script goes in the head of the page, before your styles. Lever UI does
not read the system setting on its own. The script does.
Vite
A client-only Vite app has a static index.html, so paste the script. This is
the text getColorModeScript() returns.
<!-- index.html -->
<html lang="en" data-leverui-color-mode="light">
<head>
<script>
(function () {
var saved = null;
try {
saved = localStorage.getItem('leverui-color-mode');
} catch (error) {}
var mode =
saved === 'light' || saved === 'dark'
? saved
: matchMedia('(prefers-color-scheme: dark)').matches
? 'dark'
: 'light';
var root = document.documentElement;
root.setAttribute('data-leverui-color-mode', mode);
root.classList.add(mode);
root.style.colorScheme = mode;
})();
</script>
</head>
</html>
Server rendering
Render ColorModeScript in the head of your page shell, before
HydrationScript. The
server rendering guide covers the rest.
// src/Document.tsx
import { ColorModeScript } from '@leverui/components';
import { HydrationScript, type JSX } from '@solidjs/web';
/** Render the page around the app. */
export default function Document(props: { children?: JSX.Element }): JSX.Element {
return (
<html lang="en" data-leverui-color-mode="light">
<head>
<meta charset="utf-8" />
<ColorModeScript />
<HydrationScript />
</head>
<body>{props.children}</body>
</html>
);
}
Options
| Prop | Default | Type | Description |
|---|---|---|---|
defaultMode | system | 'light' | 'dark' | 'system' | Mode used when nothing is saved. |
nonce | — | string | Nonce for your security policy. |
getColorModeScript({ defaultMode }) returns the same script as text.
What the script does
- Reads the choice saved in
localStorageunderleverui-color-mode. - With no saved choice, uses
defaultMode.systemfollows the device. - Sets
data-leverui-color-modeonhtml, adds alightordarkclass, and setscolor-schemeso native controls match.
It runs before the first paint, so there is no flash of the wrong colors. A
saved value is used only if it is exactly light or dark. If storage is
blocked, the default still applies.
A strict Content Security Policy blocks inline scripts. Pass nonce, or allow
the text from getColorModeScript() by hash. The text is the same for the same
options.
createColorMode
Call it in any component.
| Returns | Type | Description |
|---|---|---|
colorMode | Accessor<'light' | 'dark'> | Current mode: colorMode(). |
setColorMode | (mode) => void | Switch to light or dark. |
toggleColorMode | () => void | Switch to the other mode. |
Both functions change the whole page and save the choice. Every component that
calls createColorMode updates together.
createColorModeValue
Picks one of two values by mode. value() returns the first in light mode and
the second in dark mode.
const value = createColorModeValue('<light-mode-value>', '<dark-mode-value>');
For colors, prefer CSS. Lever UI's variables, such as --leverui-colors-bg and
--leverui-colors-fg, already change with the mode. For your own colors, use a
selector.
.promo {
border-color: #d4d4d8;
}
[data-leverui-color-mode='dark'] .promo {
border-color: #3f3f46;
}
Hydration Mismatch
The server does not know the visitor's mode, so createColorMode reports
light until the page is running in the browser.
Colors are never wrong, because they come from CSS and the script. Only content
you pick by mode, such as a label that says "Dark", can show its light version
for a moment. Wrap that content in ClientOnly and show a placeholder until
the browser takes over.
Do not read localStorage or the document while rendering.
ColorModeButton
A ready-made toggle: a sun in light mode, a moon in dark mode. Shows a skeleton
until the browser takes over. Takes IconButton props such as size and
variant. ColorModeIcon is the icon on its own.
Forced Color Mode
LightMode and DarkMode keep everything inside them in one mode, whatever
the page uses. They wrap Theme and work without the
Setup script.
Guides
Setting Default Color Mode
Set defaultMode on ColorModeScript, or pass it to getColorModeScript. A
saved choice still wins.
Default to light mode:
<ColorModeScript defaultMode="light" />
Default to dark mode:
<ColorModeScript defaultMode="dark" />
Respect system preference (default):
<ColorModeScript defaultMode="system" />
getColorModeScript({ defaultMode: 'dark' });
With a pasted script, paste the text that call returns.
Disabling System Preference
Set defaultMode to light or dark. The device setting is then never read.
Once a choice is saved, later changes to the device setting have no effect
either.
Using Custom Storage Key
Not supported. The mode is always saved in localStorage under
leverui-color-mode, exported as colorModeStorageKey. A different key needs
your own script and your own controls.
import { colorModeStorageKey } from '@leverui/components';
Forcing a Specific Page to Light/Dark Mode
Wrap the page in Theme. Dialogs, menus, and other overlays render at the end
of the document, outside that wrapper, so they follow the page's mode. Mount
them inside the Theme, or give them the same theme values.
import { Theme } from '@leverui/components';
import type { JSX, ParentProps } from 'solid-js';
/** Keep a route in dark mode regardless of the visitor's choice. */
export function ForcedDarkPage(props: ParentProps): JSX.Element {
return <Theme appearance="dark">{props.children}</Theme>;
}
FAQ
Do I need a theme library?
No. ColorModeScript is all you need. Any other tool also works if it sets
data-leverui-color-mode on the html element before the page paints.