Storage
The visitor’s choice is stored in localStorage as an @k8ordo/state local state. You will learn the stored shape and how to read it without the provider.
On this page
The colorSchemeState definition
scheme.tsimport { defineLocalState } from '@k8ordo/state';
import * as z from 'zod/mini';
export const colorSchemeState = defineLocalState(
'color-scheme',
The state’s name. The localStorage key is `k8ordo-state:color-scheme`
z.object({ preference: z.optional(z.enum(['light', 'dark'])) }),
Optional. Absent means “nothing chosen”
);@k8ordo/color-scheme exports this definition as colorSchemeState; there is nothing more to it. How defineLocalState works is covered in Storage and memory in @k8ordo/state.
Read the key as colorSchemeState.storageKey instead of spelling it out.
The OS setting on the first visit is never stored as a choice.
What is stored
localStorage is written only when setPreference is called. Here is what each call stores.
- Never chose: nothing is stored, and
localStorage.getItemreturnsnull. setPreference('dark'):{"preference":"dark"}is stored.setPreference('light'):{"preference":"light"}is stored.setPreference('system'):{}is stored.
When read, {} is the same as nothing stored. Both mean nothing chosen, and the provider’s default applies.
The default is never stored. What changing defaultPreference does is covered in Switch.
A browser that blocks site data cannot store a choice. The provider renders defaultPreference, and a scheme set with setPreference stays in memory until the next load.
Reading without the provider
stored-preference.tsx'use client';
import { colorSchemeState } from '@k8ordo/color-scheme';
import { useAppState } from '@k8ordo/state';
export function StoredPreference() {
const [{ preference }] = useAppState(colorSchemeState);
return <output>{preference ?? 'nothing chosen'}</output>;
}Any Client Component reads the same value as the provider with useAppState(colorSchemeState). It returns the stored preference: 'light', 'dark' or undefined. In the server render and the hydration render, it is undefined.
For the scheme currently applied, use scheme from useColorScheme().
An inline script of your own that runs before the first paint uses colorSchemeState.inlineRead(). It returns a JavaScript expression that evaluates to the stored object or null. No schema runs there, so check each field you use. See Before hydration in @k8ordo/state.
Syncing across tabs
A choice made in another tab reaches this tab’s provider through the storage event, and the class on <html> changes in place. The same happens when another tab clears localStorage.
Pitfall
The storage event does not fire in the tab that wrote. A direct localStorage.setItem in the same tab is not reflected in the provider until a reload. Change the choice through setPreference.
Other preferences
Store other display preferences in a defineLocalState of your own under another name. See Storage and memory in @k8ordo/state.
Pitfall
Do not define another defineLocalState('color-scheme', …) in the application. Stores are shared by name, so both definitions read and write the same localStorage key.