Getting Started
Install and configure @wrksz/themes in your Next.js app.
Edit on GitHub
Last updated on
These docs describe 2.0.0-beta.1. Install with the beta tag. Stable latest is still 1.2.0. See Upgrading from 1.x.
Installation
bun add @wrksz/themes@betanpm install @wrksz/themes@betapnpm add @wrksz/themes@betayarn add @wrksz/themes@betaSetup
Add ThemeProvider to your root layout. Import from @wrksz/themes/next for Next.js - this avoids the React 19 inline script warning by using useServerInsertedHTML. Add suppressHydrationWarning to <html> to prevent hydration mismatches.
import { ThemeProvider } from "@wrksz/themes/next";
export default function RootLayout({ children }: { children: React.ReactNode }) {
return (
<html lang="en" suppressHydrationWarning>
<body>
<ThemeProvider>{children}</ThemeProvider>
</body>
</html>
);
}Usage
Use the useTheme hook in any Client Component to read and update the current theme.
"use client";
import { useTheme } from "@wrksz/themes/client";
export function ThemeToggle() {
const { resolvedTheme, setTheme } = useTheme();
return (
<button
type="button"
onClick={() => setTheme(resolvedTheme === "dark" ? "light" : "dark")}
>
Toggle theme
</button>
);
}Import paths
| Import | Use for |
|---|---|
@wrksz/themes/next | ThemeProvider in Next.js (recommended) |
@wrksz/themes/client | useTheme, useThemeValue, useThemeEffect, ThemedImage, ClientThemeProvider, createThemes |
@wrksz/themes/client/use-theme | Direct useTheme import |
@wrksz/themes/client/use-theme-value | Direct useThemeValue import |
@wrksz/themes/client/use-theme-effect | Direct useThemeEffect import |
@wrksz/themes/client/themed-image | Direct ThemedImage import |
@wrksz/themes/client/provider | Direct ClientThemeProvider import |
@wrksz/themes/client/create-themes | Direct createThemes import |
@wrksz/themes | Client-safe ThemeProvider alias and createThemes for framework-neutral React usage |
The API is identical to next-themes. Migrating requires changing one import line: @wrksz/themes/next instead of next-themes. See Why not next-themes? for a full comparison.
Requirements
- Next.js 16+
- React 18+ (uses native
useEffectEventon React 19.2+) - TypeScript 5.9+ Breaking · v2.0.0-beta.1 (
typescriptpeer is>=5.9from2.0.0-beta.1; 4.x and 5.0–5.8 are unsupported on this line)
Next steps
- ThemeProvider API - all available props
- useTheme API - hook reference
- Examples - Tailwind, data attributes, scoped theming, and more