Overview

usePreferredColorScheme is part of the @usefy ecosystem — a collection of production-ready, TypeScript-first, SSR-safe React hooks. Track the user's preferred color scheme (prefers-color-scheme).

Features

• Live — reflects OS theme changes immediately
• SSR-safe — configurable default scheme
• Primitive — pair with your own persistence for a full theme
• TypeScript-first — full type inference and exported types
• Tiny & tree-shakeable — zero dependencies, published as its own package

Installation

# npm
npm install @usefy/use-preferred-color-scheme

# yarn
yarn add @usefy/use-preferred-color-scheme

# pnpm
pnpm add @usefy/use-preferred-color-scheme

Requires React 18 or 19 (peerDependencies: "react": "^18.0.0 || ^19.0.0").

Quick Start

import { usePreferredColorScheme } from "@usefy/use-preferred-color-scheme";

const scheme = usePreferredColorScheme(); // "light" | "dark"

API

usePreferredColorScheme(options?): "light" | "dark"

• options.defaultScheme — scheme returned on the server / when matchMedia is unavailable (default "light").
• options.initializeWithValue — when true (default), the real preference is read synchronously on the first client render. Set to false to render defaultScheme on the first client render and defer the real read to a post-commit effect, avoiding a hydration mismatch when the server rendered defaultScheme.

Testing

📊 View Detailed Coverage Report (GitHub Pages) — 8 tests, 100% statement coverage.

License

MIT © mirunamu

This package is part of the usefy monorepo.