next-themes

next-themes is a lightweight React library that adds complete theme support—including dark mode, light mode, and any number of custom themes—to Next.js and other React applications. It solves the two hardest parts of theme switching in an SSR/SSG environment: the flash of incorrect theme on page load and keeping theme state synchronized across browser tabs.

At its core is a ThemeProvider component and a useTheme hook that expose the active theme, the resolved system theme, and a setTheme function, while a synchronously-injected inline script updates the data-theme or class attribute on the <html> element before React hydrates, eliminating any visible flicker.

What You Get

• ThemeProvider component that manages theme state and injects a pre-hydration script to avoid flash-of-incorrect-theme
• useTheme hook exposing theme, resolvedTheme, systemTheme, themes, and setTheme
• Automatic prefers-color-scheme detection with live updates when the OS theme changes
• Cross-tab theme synchronization via the storage event
• Support for unlimited custom theme names, not just light/dark, via the themes prop
• Forced-theme support for locking individual pages/routes to a specific theme

Common Use Cases

• Adding a dark mode toggle to a Next.js app/ or pages/ router app
• Building multi-theme products (e.g. brand-selectable themes) beyond light/dark
• Locking marketing or landing pages to a single forced theme regardless of user preference
• Persisting and syncing a user’s theme choice across multiple open tabs

Under The Hood

Architecture

The library exposes a React Context-based ThemeProvider around a single component (src/index.tsx, 263 lines) that manages theme state via useState, syncing it to localStorage and to a data-theme/class attribute on document.documentElement. To avoid a flash of the wrong theme on first paint, it injects a synchronously-executed inline <script> tag (ThemeScript, memoized) whose body is the stringified script function from src/script.ts — this runs before React hydrates, reading localStorage and applying the DOM attribute/class immediately. useEffect hooks wire up a matchMedia('(prefers-color-scheme: dark)') listener for system-theme changes and a window.addEventListener('storage', ...) listener to sync theme across tabs. src/types.ts defines the public ThemeProviderProps/UseThemeProps contracts. The package is a single flat module with no internal composition or external state library — just React Context, two effects, and one inlined bootstrap script.

Tech Stack

TypeScript with only react/react-dom as peer dependencies (16.8 through 19), built via tsup into ESM and CJS bundles plus .d.ts types (minified, tree-shaken, bundle: true). Tested with Vitest (__tests__/index.test.tsx, 502 lines) plus a focused root-level test/ suite (forced-theme, storage-event, system-theme, switch-theme) and Playwright end-to-end tests (playwright.config.ts, .github/workflows/e2e.yml). The repo is a pnpm + Turborepo monorepo (pnpm-workspace.yaml, turbo.json) with the publishable package isolated under next-themes/, and GitHub Actions runs both the unit and e2e workflows on every push.

Code Quality

Test coverage is strong relative to the codebase’s size — 373 lines of source paired with 500+ lines of unit tests and a 5-file Playwright e2e suite covering the trickiest edge cases (hydration timing, forced themes, storage sync, system-theme changes). The code favors a terse, framework-free style, guards localStorage access with try/catch for disabled-storage and SSR environments (isServer check), and keeps its public surface intentionally minimal. Minor rough edges: tsconfig.json sets strict: false, and a couple of empty catch (e) { // Unsupported } blocks silently swallow storage errors rather than logging — acceptable for a browser-storage guard, but worth noting.

API Design The public API is just two exports — <ThemeProvider> and useTheme() — with sensible defaults (defaultTheme: 'system', attribute: 'data-theme') that make a working dark-mode integration genuinely “two lines of code,” matching the README’s own framing. Props are documented inline via TSDoc comments in types.ts, and the README (18KB) devotes a section to nearly every configuration knob — class vs. data-attribute output, forced themes, differing DOM/theme names, CSS-in-JS integration, Cloudflare Rocket Loader compatibility — plus explicit hydration-mismatch guidance. There’s no CLI and no required build step for consumers; it’s a pure drop-in React component.