@k8ordo/color-scheme

Troubleshooting

Common symptoms, their causes and their fixes. To look up an error, search this page for its wording.

On this page

Light theme flashing on reload

Cause

The inline script did not run before the first paint. Usually a CSP blocked it, or the script comes after a stylesheet and waits for it to load.

Fix

If the console reports a CSP violation, see “Inline script blocked by CSP” below. Otherwise put <ColorSchemeScript /> in the root layout’s <head>. Without @k8ordo/framework, check that the HTML as sent has the script ahead of every stylesheet.

Inline script blocked by CSP

Cause

A policy that restricts scripts does not allow the inline one. When it is allowed by hash, the hash may have been computed for a different defaultPreference or themeColor than ColorSchemeScript’s, or copied from an older version.

Fix

To allow it by nonce, pass the request’s nonce to ColorSchemeScript’s nonce (nonce() in @k8ordo/framework’s server mode). To allow it by hash, pass ColorSchemeScript’s defaultPreference and themeColor to colorSchemeScriptHash() and compute the hash each time you build the policy, instead of copying it. Do not use 'unsafe-inline': it allows every other inline script too. See CSP.

A tree hydrated but some attributes of the server rendered HTML didn't match

Cause

The class="dark" the inline script added is not in the server’s HTML. React’s development build compares <html>’s attributes with its props and warns about the class.

Fix

Give <html> suppressHydrationWarning. It silences the warning for <html>’s own attributes only; mismatches inside the page are still reported. Hydration does not write attributes back, so the class stays.

Form controls in the other scheme

Cause

What the browser draws itself follows the CSS color-scheme property. This package does not set it, so without @k8ordo/ui you declare it yourself. Declared as color-scheme: light dark, the browser picks by the OS setting, which can differ from the visitor’s choice.

Fix

Declare color-scheme: light on :root and color-scheme: dark on .dark. See Styling.

Tailwind CSS’s dark: ignoring the class

Cause

Tailwind CSS 4’s dark: reads prefers-color-scheme by default. It follows the OS setting, not the visitor’s choice.

Fix

Declare @custom-variant dark (&:where(.dark, .dark *)); in the stylesheet, and dark: reads the class. @k8ordo/ui’s tailwind.css already declares it. See Styling.

An icon in the other scheme just after loading

Cause

The server cannot read the stored choice, so it renders the default. Markup that branches on scheme stays in the default scheme until hydration finishes.

Fix

Render both and hide one with dark:, or call use(browser()) inside a <Suspense> so it renders in the browser only. See Switch.

useColorScheme needs <ColorSchemeProvider> above it

Cause

There is no provider above the component that called useColorScheme(). Commonly the provider sits in a nested layout, or a test renders without a wrapper.

Fix

Put the provider in the root layout, inside <body>, around the whole page. In a test, pass it to renderHook as the wrapper.

A scheme that ignores the OS setting

Cause

The OS setting applies only while the visitor has chosen nothing. Once they pick light or dark, that choice wins. With a defaultPreference other than 'system', the OS setting is not used either.

Fix

setPreference('system') clears the stored choice, and the default applies again. Give the switch a third option, “System”, so visitors can go back themselves.

A scheme unchanged by a localStorage write

Cause

Tabs pass the choice along through the storage event, which never fires in the tab that wrote. A direct localStorage.setItem in the same tab goes unnoticed by the provider until a reload.

Fix

Change the choice through setPreference. Other tabs on the same origin follow. See Storage.

Encountered a script tag while rendering React component

Cause

Rendered in the browser only, as in a test, React does not execute the inline <script> that ColorSchemeScript renders. Its development build logs that as an error.

Fix

In a test, leave ColorSchemeScript out and pass only the provider as the wrapper. The class a test sees on <html> is written by the provider’s effect. See Testing.

k8ordo

React libraries that use Baseline features without holding back.