Getting Started

Installation

bun add @wrksz/themes

npm install @wrksz/themes

pnpm add @wrksz/themes

yarn add @wrksz/themes

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.

app/layout.tsx

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.

components/theme-toggle.tsx

"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>
  );
}

What's new in v0.9.0

Since v0.9.0

storage="hybrid" combines cookie SSR correctness with localStorage cross-tab sync.
createThemes(...) gives a typed factory so your theme union is inferred once and reused everywhere.
useThemeEffect(...) runs theme side effects after mount when theme/resolvedTheme changes.

app/theme.ts

"use client";
import { createThemes } from "@wrksz/themes/client";

export const { ThemeProvider, useTheme, useThemeValue, useThemeEffect } = createThemes({
  themes: ["light", "dark", "high-contrast"] as const,
  defaultTheme: "system",
  storage: "hybrid",
  attribute: "class",
});

Import paths

Since v0.9.2

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`	`ThemeProvider`, `createThemes` for non-Next.js frameworks

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 19+

Next steps

ThemeProvider API - all available props
useTheme API - hook reference
Examples - Tailwind, data attributes, scoped theming, and more