next-themes

Perfect dark mode for React and Next.js apps in two lines of code, with zero flash on load.

Library

npm

v0.4.6

6,330stars

MIT License

View Source Visit Website

On This Page

Repository Health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →

45/100Fair

Development Activity4

Maintenance20

Community56

Maturity60

Momentum40

Technical Analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation.How we score it →

86/100Excellent

Architecture78

Code Quality84

Innovation90

Learning Curve92

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.

Used by 89 apps in this directory

TypeScript

76%

AGPL 3.0

Abby

Developer Tools · Product Management

167

Statically typed feature flags, remote config, and A/B testing with framework-native SDKs for TypeScript teams.

AFFiNE

Productivity · Project Management · Note Taking

71,668

Write, draw, and plan in one infinite canvas — the open-source alternative to Notion and Miro that keeps your data yours.

Apache Airflow

Data Engineering

46,530

Define, schedule, and monitor complex data workflows as Python code — with a powerful UI, 80+ provider integrations, and battle-tested scalability across thousands of production deployments.