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.

Code
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.

Code
<!-- 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.

Code
// 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

PropDefaultTypeDescription
defaultModesystem'light' | 'dark' | 'system'Mode used when nothing is saved.
nonce—stringNonce for your security policy.

getColorModeScript({ defaultMode }) returns the same script as text.

What the script does

  1. Reads the choice saved in localStorage under leverui-color-mode.
  2. With no saved choice, uses defaultMode. system follows the device.
  3. Sets data-leverui-color-mode on html, adds a light or dark class, and sets color-scheme so 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.

ReturnsTypeDescription
colorModeAccessor<'light' | 'dark'>Current mode: colorMode().
setColorMode(mode) => voidSwitch to light or dark.
toggleColorMode() => voidSwitch 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.

Code
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.

Code
.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:

Code
<ColorModeScript defaultMode="light" />

Default to dark mode:

Code
<ColorModeScript defaultMode="dark" />

Respect system preference (default):

Code
<ColorModeScript defaultMode="system" />
Code
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.

Code
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.

Code
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.