@dazl/color-scheme

A color scheme management library for web applications with support for light/dark themes and automatic system preference detection.

@dazl/color-scheme is a library for managing light/dark color schemes in web applications. It handles system preference detection, persistent storage, and CSS class application, with a React hook for integration into your components.

Installation

npm install @dazl/color-scheme

Features

Light/Dark/System modes: supports explicit light or dark, or automatic OS-level detection
System preference detection: responds to changes in the OS theme in real time
React integration: useColorScheme hook for React components
Persistent storage: remembers user preference via localStorage
CSS class management: automatically applies theme classes to the document root
Style injection: injects the color-scheme CSS property on <html> for native browser theming
Zero dependencies: no external runtime dependencies
TypeScript support: full type definitions included

Client-side Setup

Import the client module to initialize color scheme management.

This must run in client-side code, before the body is rendered. Place it in an inline script.

import "@dazl/color-scheme/client";

// The color scheme API is now available globally
const currentScheme = window.colorSchemeApi.current;
console.log(currentScheme); // { config: 'system', resolved: 'dark' }

// Change the color scheme
window.colorSchemeApi.config = "light";

// Subscribe to changes
const unsubscribe = window.colorSchemeApi.subscribe(({ config, resolved }) => {
  console.log(`Color scheme changed: ${config} (resolved: ${resolved})`);
});

Color-scheme API (`window.colorSchemeApi`)

Property / Method	Type	Description
`config`	`'light' \| 'dark' \| 'system'`	Get or set the current color scheme configuration
`currentState`	`{ config: 'light' \| 'dark' \| 'system', resolved: 'light' \| 'dark' }`	Current state including both config and resolved values
`resolvedSystem`	`'light' \| 'dark'`	Resolved theme based on OS/system preferences
`subscribe`	`(handler: (state) => void) => () => void`	Subscribe to color scheme changes; returns an unsubscribe function
`getRootCssClass`	`(resolved?: 'light' \| 'dark') => string`	CSS class applied to the document root for the given (or current) resolved theme

Override root CSS class

By default, dark-theme and light-theme are applied to the document root. Override them with data-dark-class and data-light-class attributes on the client script tag:

<script
  src="@dazl/color-scheme/client"
  data-dark-class="dark-theme"
  data-light-class="light-theme"
></script>

React Integration

Use the useColorScheme hook to read and update the color scheme in React components:

import { useColorScheme } from "@dazl/color-scheme/react";

function ThemeToggle() {
  const { configScheme, resolvedScheme, setColorScheme, isLight, isDark } =
    useColorScheme();

  return (
    <div>
      <p>Current config: {configScheme}</p>
      <p>Resolved theme: {resolvedScheme}</p>
      <p>Is light theme: {isLight}</p>
      <p>Is dark theme: {isDark}</p>

      <button onClick={() => setColorScheme("light")}>Light Theme</button>
      <button onClick={() => setColorScheme("dark")}>Dark Theme</button>
      <button onClick={() => setColorScheme("system")}>System Theme</button>
    </div>
  );
}

Hook API (`useColorScheme`)

Property	Type	Description
`resolvedScheme`	`'light' \| 'dark'`	Resolved theme (never `'system'`)
`configScheme`	`'light' \| 'dark' \| 'system'`	Current stored configuration
`setColorScheme`	`(config: 'light' \| 'dark' \| 'system') => void`	Update the color scheme
`isLight`	`boolean`	`true` when the resolved theme is light
`isDark`	`boolean`	`true` when the resolved theme is dark
`rootCssClass`	`string`	CSS class currently applied to the document root

CSS Styling

The library applies a class to <html> based on the resolved theme. The default classes are dark-theme and light-theme:

:root.dark-theme {
  --bg-color: #000000;
  --text-color: #ffffff;
}

:root.light-theme {
  --bg-color: #ffffff;
  --text-color: #000000;
}

Working with the Theme – how Dazl manages theme tokens and design system colors in the editor
Add-ons – pre-built recipes for installing libraries into your Dazl project

@dazl/color-scheme

On this page