Get Started
Build one button that switches between light and dark with @k8ordo/color-scheme.
On this page
Install
npm install @k8ordo/color-scheme @k8ordo/state zodIt 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.
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.tsximport {
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.
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.
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>.
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.
Switch demo
The button built on this page, wired to this site’s provider.
Try it
- Press the button. The whole site switches, and the label flips to the other scheme.
- Press the color scheme switch in the header. This button’s label changes with it: both read the same provider.
- With the site dark, reload the page. It comes back dark from the start, with no white flash.