@k8ordo/color-scheme

Get Started

Build one button that switches between light and dark with @k8ordo/color-scheme.

On this page

Install

bash
npm install @k8ordo/color-scheme @k8ordo/state zod

It runs with:

  • React 19.3 or later
  • TypeScript 7 or later, when you write TypeScript

The guide for AI agents ships at node_modules/@k8ordo/color-scheme/docs/GUIDE.md. Point your AGENTS.md or the like at that path.

Information

Note

The provider stores the chosen scheme in localStorage as an @k8ordo/state local state, which is why @k8ordo/state and zod are needed. What is stored is described in Storage.

In the root layout

src/routes/layout.tsx
import {
  ColorSchemeProvider,
  ColorSchemeScript,
} from '@k8ordo/color-scheme';
import type { ReactNode } from 'react';

export default function RootLayout({
  children,
}: {
  children: ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
Silences the warning about the class the script adds
      <head>
        <ColorSchemeScript />
Puts the class on before the first paint
      </head>
      <body>
        <ColorSchemeProvider>{children}</ColorSchemeProvider>
Wraps the whole page
      </body>
    </html>
  );
}

Put <ColorSchemeScript /> in the root layout’s <head>, and <ColorSchemeProvider> inside its <body>, around the whole page. The provider is a Client Component, but the root layout can stay a Server Component.

ColorSchemeScript renders an inline <script>. The script reads the stored choice, or follows the OS setting when nothing is stored. When that is dark, it puts the dark class on <html> before the first paint.

The class is not in the server’s HTML. Without suppressHydrationWarning on <html>, React reports a hydration mismatch in development.

Information

Note

The script has to come before every stylesheet. After one, it waits for that stylesheet to load, and the browser may paint the page light in the meantime. @k8ordo/framework moves the inline scripts written in <head> ahead of the stylesheets.

Colors for the dark class

globals.css
:root {
  color-scheme: light;
  --page-bg: #ffffff;
  --page-fg: #1f1f1f;
}

:root.dark {
The colors while the `dark` class is on
  color-scheme: dark;
  --page-bg: #1f1f1f;
  --page-fg: #f5f5f5;
}

body {
  background: var(--page-bg);
  color: var(--page-fg);
}

All this package changes is the dark class on <html>. The stylesheet decides the colors.

Switch color-scheme along with the colors, and what the browser draws itself, such as scrollbars and form controls, follows the chosen scheme too.

Information

Note

With @k8ordo/ui’s stylesheet loaded, its tokens and color-scheme already switch on this class. Using it with Tailwind CSS’s dark: is covered in Styling.

Switching with the hook

scheme-toggle.tsx
'use client';

import { useColorScheme } from '@k8ordo/color-scheme';

export function SchemeToggle() {
  const { scheme, setPreference } = useColorScheme();
`scheme` is what is on screen
  const next = scheme === 'dark' ? 'light' : 'dark';

  return (
    <button
      onClick={() => {
        setPreference(next);
Stores the chosen scheme
      }}
      type="button"
    >
      Switch to {next}
    </button>
  );
}

Call useColorScheme() in a Client Component to get scheme and setPreference. A scheme passed to setPreference is stored in localStorage, and the provider swaps the class on <html>.

Information

Note

The label comes from scheme. Until hydration, it matches the default scheme of the server render. How to avoid that is covered in Switch.

Playground

Switch demo

The button built on this page, wired to this site’s provider.

Try it

  1. Press the button. The whole site switches, and the label flips to the other scheme.
  2. Press the color scheme switch in the header. This button’s label changes with it: both read the same provider.
  3. With the site dark, reload the page. It comes back dark from the start, with no white flash.
k8ordo

React libraries that use Baseline features without holding back.