Build a switch

Call useColorScheme() in a Client Component and it returns three things, decided by the provider in the root layout.

• scheme: what is on screen, 'light' or 'dark'. It comes from the visitor’s choice, the provider’s default, or the OS setting.
• preference: what the visitor chose, 'light', 'dark' or 'system'. It is 'system' while nothing is chosen.
• setPreference: stores a choice. Passing 'system' clears the stored choice, so the provider’s default applies again.

The hook only reads what the provider decided; it never touches the class on <html> or localStorage. However many switches a page has, one provider decides for all of them, so they never disagree.

To flip between light and dark, read scheme and store the other one.

'use client';

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

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

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

It reads scheme, not preference, because while nothing is chosen preference is 'system', which does not say which way to go.

One press stores a choice, and from then on changing the OS setting no longer changes the scheme. To let visitors go back to following the OS, offer the three-way choice below. The switch in this site’s header is this toggle.

To let the visitor choose to follow the OS as well, use preference as the value of the choice.

'use client';

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

export function SchemeSelect() {
  const { scheme, preference, setPreference } = useColorScheme();

  return (
    <select
      onChange={(event) => {
        setPreference(
          event.currentTarget.value as ColorSchemePreference,
        );
      }}
      value={preference}
    >
      <option value="system">System ({scheme})</option>
      <option value="light">Light</option>
      <option value="dark">Dark</option>
    </select>
  );
}

setPreference('system') clears the stored choice. So preference reads 'system' both for a visitor who never chose and for one who chose and went back.

Showing scheme beside the system option tells the visitor which scheme the OS setting gives right now.

What a visitor who chose nothing gets is the provider’s defaultPreference. Left out, it is 'system', which follows the OS setting.

<ColorSchemeProvider defaultPreference="dark">
  {children}
</ColorSchemeProvider>

The default is never stored. Change it later, and every visitor who has not chosen moves to the new default, while those who chose keep their choice. The inline script carries the same default, so the first paint starts from it too.

With a default other than 'system', a “System” option no longer says what it does: as a preference, 'system' means “nothing chosen”, not “follow the OS”. Label it something like “Default” instead.

A server cannot read localStorage, so the provider renders the default there; with a 'system' default, the scheme it renders is 'light'. An icon or a label chosen from scheme therefore shows the server’s guess until hydration.

The page’s colours are right from the first paint, because they follow the dark class the inline script put on. Only markup chosen in React’s render is off, and there are two ways to fix it.

export function SchemeToggle() {
  const { scheme, setPreference } = useColorScheme();

  return (
    <button
      onClick={() => {
        setPreference(scheme === 'dark' ? 'light' : 'dark');
      }}
      type="button"
    >
      <span className="dark:hidden">Switch to dark</span>
      <span className="hidden dark:inline">Switch to light</span>
    </button>
  );
}

'use client';

import { useColorScheme } from '@k8ordo/color-scheme';
import { Suspense, use } from 'react';
import { browser } from 'react-dom';

import { MoonIcon, SunIcon } from './icons';

function SchemeIcon() {
  use(browser('the stored preference is in localStorage'));
  const { scheme } = useColorScheme();
  return scheme === 'dark' ? <MoonIcon /> : <SunIcon />;
}

export function SchemeToggle() {
  const { scheme, setPreference } = useColorScheme();

  return (
    <button
      aria-label="Toggle colour scheme"
      onClick={() => {
        setPreference(scheme === 'dark' ? 'light' : 'dark');
      }}
      type="button"
    >
      <Suspense fallback={<span className="size-5" />}>
        <SchemeIcon />
      </Suspense>
    </button>
  );
}