nextjs-themes

nextjs-themes is an open-source theming library for Next.js 13 and 14 App Router that implements dark mode in two lines of code without wrapping the app in a provider, preserving React Server Component benefits.

What is nextjs-themes?

nextjs-themes is a TypeScript library by Mayank Kumar Chaudhari that manages light/dark/system themes in Next.js projects using the app directory. It takes theme preferences from the user's system and exposes a useTheme hook and CSS data attributes so developers can style components for multiple themes. The library is published on npm as nextjs-themes, with a lite variant nextjs-themes-lite that requires r18gs as a peer dependency. It is documented with Typedoc and licensed under MPL-2.0.

What makes nextjs-themes stand out?

• No provider wrapper — Unlike next-themes, this library does not require wrapping the entire application in a context provider, so Server Components keep their server-rendered benefits.
• Tree-shakable imports — Import from nextjs-themes/client/component to include only the code the app actually uses.
• Zero flash on load — Works with SSG, SSR, ISG, and Server Components to avoid theme flashing during page load.
• Cross-tab synchronization — Theme changes sync across browser tabs and windows automatically.
• Flexible theme selectors — Supports class selectors and data attributes including data-th, data-color-scheme, and data-csp for styling variants.
• System preference support — Uses prefers-color-scheme and applies color-scheme to theme the browser UI itself.
• Forced themes per page — Can force specific pages to a particular theme regardless of the user's setting.
• Next.js 13 and 14 appDir support — Built specifically for the App Router, with full TypeScript support.

Who should use nextjs-themes?

• Next.js App Router developers who want dark mode without sacrificing React Server Components or adding a provider layer.
• Library maintainers building themeable UI kits who need a small, tree-shakable theming dependency.
• Teams migrating from next-themes who want a drop-in replacement with extra features like data-csp and forced page themes.

Use cases

• SaaS applications: Add light/dark/system theme switching to a Next.js dashboard while keeping Server Components streaming.
• Content-heavy blogs: Style markdown content with data-theme selectors so code blocks and prose adapt to the active theme.
• Component library developers: Offer a theming primitive that works across Next.js projects and supports both class and data-attribute selectors.

How does nextjs-themes work?

The library reads the user's system color scheme via prefers-color-scheme, then sets a data-theme attribute on the document element. The useTheme hook returns the current theme, a resolvedTheme that resolves the "system" value to an actual light/dark value, and a resolvedColorScheme for color-scheme preference. Developers call an initialization function (typically in the root layout) and use the hook in client components to toggle themes. For automated testing, the repository includes a test workflow and Codecov coverage.

Alternatives

• next-themes — The library that inspired nextjs-themes; it requires wrapping the app in a provider and does not expose data-csp.

FAQ

Do I need to use CSS variables with this library?

No. You can hard-code values for every class and use selectors like [data-theme="dark"] .my-class to override styles for dark mode. CSS variables are optional.

Why is resolvedTheme necessary?

Because when a user selects "system", resolvedTheme tells you whether the system preference resolved to light or dark, which you need for runtime styles such as setting the correct background color.

Is nextjs-themes free?

Yes, the library is open source under the MPL-2.0 license.

Does nextjs-themes support Next.js 12 Pages Router?

The content specifies support for Next.js 13 and 14 App Router; no Pages Router support is mentioned.

What is the lite version?

nextjs-themes-lite is a smaller variant for projects that already use r18gs, since it requires r18gs as a peer dependency.