@dazl/color-scheme

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

Features

🌓 Light/Dark/System modes - Support for light, dark, and automatic system preference detection
📱 System preference detection - Automatically responds to OS-level theme changes
⚛️ React integration - Ready-to-use React hook for seamless integration
💾 Persistent storage - Remembers user preferences using localStorage
🎨 CSS class management - Automatically applies theme classes to document root
🏷️ Automatic style injection - Injects the color-scheme CSS property on the document root for native browser theming
📦 Zero dependencies - Lightweight with no external dependencies
🔧 TypeScript support - Full TypeScript definitions included

Installation

npm install @dazl/color-scheme

Usage

Client-side Setup

Import the client module to initialize color scheme management:

Note: This import should only be used in client-side code and must run before the <body> is rendered. For best results, include 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

config (light|dark|system) - Get or set the current color scheme configuration
currentState ({ config: light|dark|system, resolved: light|dark }) - Get the current state including both config and resolved values
resolvedSystem (light|dark) - Get the resolved theme based on system preferences
subscribe ((handler: (currentState) => void) => () => void) - Subscribe to color scheme changes and return an unsubscribe function
getRootCssClass ((resolved?: light|dark) => string) - CSS class applied to the document root based on the resolved theme or passed value

Override root CSS class

Override the default CSS classes applied to the document root by specifying data-dark-class and data-light-class attributes in 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 provided React hook for easy integration:

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

resolvedScheme (light|dark) - Resolved theme (light/dark)
configScheme (light|dark|system) - Current configuration (light/dark/system)
setColorScheme ((config: light|dark|system) => void) - Function to change the color scheme
isLight (boolean) - Whether the current resolved theme is light
isDark (boolean) - Whether the current resolved theme is dark
rootCssClass (string) - CSS class applied to the document root based on the resolved theme

CSS Styling

The library automatically applies CSS classes to the document root. Style your application accordingly:

/* Dark theme styles */
:root.dark-theme {
  --bg-color: #000000;
  --text-color: #ffffff;
}

/* Light theme styles (explicit) */
:root.light-theme {
  --bg-color: #ffffff;
  --text-color: #000000;
}

JSPM