Skip to Content

Color Scheme

Read an element's computed light or dark color scheme with an SSR-safe React hook.

useColorScheme reads the computed value of the CSS color-scheme property. By default, it checks document.documentElement and updates when that element's class, style, or data-theme attribute changes.

Usage

import { useColorScheme } from "@puzzle-ui/hooks";

function ColorSchemeStatus() {
  const scheme = useColorScheme();

  return <p>Active color scheme: {scheme ?? "Detecting"}</p>;
}

The value is undefined during server rendering and until the client effect reads the computed style. A value containing dark returns "dark"; other computed values return "light".

Custom target and property

Pass a function that returns the element to inspect and the CSS property to read. The target function runs from an effect, so it can safely query the document without accessing browser globals during server rendering.

const scheme = useColorScheme({
  target: () => document.querySelector<HTMLElement>("[data-theme-root]"),
  property: "--page-color-scheme",
});

The hook observes class, style, and data-theme attribute changes on the target. It does not subscribe directly to the system prefers-color-scheme media query; use useReducedMotion for the corresponding motion preference.

API

type ColorScheme = "light" | "dark";

type UseColorSchemeOptions = {
  target?: () => HTMLElement | null;
  property?: string;
};

useColorScheme(options?: UseColorSchemeOptions): ColorScheme | undefined;