ThemeProvider

ThemeProvider wraps your app, injects an anti-flash script before hydration, and manages theme state via ClientThemeProvider.

When rendered from a Server Component, the Next providers generate the bootstrap string on the server and pass it to the client boundary. The generator stays out of that client bundle; the script string is included in the HTML and the RSC payload. The typed Next factory remains a client-side path and still includes the generator. See createThemes.

Two variants are available depending on your framework:

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

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

export function Providers({ children }) {
  return <ThemeProvider>{children}</ThemeProvider>;
}

import { ThemeProvider } from "@wrksz/themes/next";

export default function RootLayout({ children }) {
  return (
    <html suppressHydrationWarning>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

Props

Extended provider

Heavier capabilities stay behind opt-in imports so the default provider bundle does not grow. @wrksz/themes/next/extended is synchronous and does not call cookies(), matching the default Next provider.

Security notes

ThemeProvider injects a small inline script to apply the initial theme before React hydrates. Configuration values are escaped for the <script> context, including themeColor, value, themes, forcedTheme, and initialTheme.

When your app uses a Content Security Policy, pass a request-scoped nonce and include the same value in script-src.

Cookie storage treats cookies as untrusted input. Stored values are validated against themes when provided, malformed cookie encoding falls back to defaultTheme, and cookie attributes are validated before writes.

Examples

Custom themes

const themes = ["light", "dark", "high-contrast"] as const;

<ThemeProvider themes={themes} defaultTheme="high-contrast">
  {children}
</ThemeProvider>

For full end-to-end inference across setTheme, useThemeValue, and theme-aware components, use createThemes with the same tuple.

Data attribute instead of class

<ThemeProvider attribute="data-theme">
  {children}
</ThemeProvider>

Multiple classes per theme

Map a theme to multiple CSS classes using a space-separated value:

<ThemeProvider
  themes={["light", "dark", "dim"]}
  value={{ light: "light", dark: "dark high-contrast", dim: "dark dim" }}
>
  {children}
</ThemeProvider>

Force a theme per page

<ThemeProvider forcedTheme="dark">
  {children}
</ThemeProvider>

Server-provided theme

Use initialTheme to initialize from a server-side source (database, session, cookie) on every mount:

export default async function RootLayout({ children }) {
  const userTheme = await getUserTheme();

  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          initialTheme={userTheme ?? undefined}
          onThemeChange={saveUserTheme}
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Cookie storage (zero-flash SSR)

When using @wrksz/themes/next, storage="cookie" keeps the provider in the static App Shell. Its bootstrap reads document.cookie synchronously and applies the class before the first paint:

import { ThemeProvider } from "@wrksz/themes/next";

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider
          attribute="class"
          defaultTheme="dark"
          storage="cookie"
          disableTransitionOnChange
        >
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Theme changes are written to the cookie automatically. If server-rendered markup must also depend on the theme, use getTheme explicitly.

Hybrid storage (SSR + cross-tab sync)

storage="hybrid" combines the best parts of cookie and local storage:

• Read priority: cookie first, then localStorage
• Writes: cookie and localStorage
• App Shell: the bootstrap reads the cookie without making the layout request-time dynamic (1.x used server cookies() here)
• Cross-tab: changes propagate through the storage event

import { ThemeProvider } from "@wrksz/themes/next";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider storage="hybrid" defaultTheme="system">
          {children}
        </ThemeProvider>
      </body>
    </html>
  );
}

Next.js 16.3 Instant Navigations

ThemeProvider does not call request-time APIs, so it can stay in a reusable App Shell when cacheComponents and partialPrefetching are enabled. Prefetches only render the static provider configuration; they never write theme cookies.

next/root-params is available by default in Next.js 16.3. Themes do not require a root-param integration. If your product intentionally stores a different theme per tenant or locale, scope the key in your app:

import { tenant } from "next/root-params";
import { ThemeProvider } from "@wrksz/themes/next";

export default async function TenantLayout({ children }) {
  const currentTenant = await tenant();
  return (
    <ThemeProvider storageKey={`theme-${currentTenant}`}>
      {children}
    </ThemeProvider>
  );
}

Sharing cookie across subdomains

Use cookieOptions.domain to share the theme preference between subdomains (e.g. app.example.com and api.example.com).

Works with both storage="cookie" and storage="hybrid":

<ThemeProvider
  storage="hybrid"
  cookieOptions={{ domain: ".example.com" }}
>
  {children}
</ThemeProvider>

All cookieOptions fields have sensible defaults - you only need to specify what you want to override.

Suppress transitions on theme change

Suppress CSS transitions only when the library actually changes the applied theme: during the inline script's initial run when SSR markup needs correction, and whenever the user switches themes. This prevents first-paint flash and animated jank without reinserting a transition override during no-op hydration:

<ThemeProvider disableTransitionOnChange>
  {children}
</ThemeProvider>

To keep some transitions intact (e.g. hover effects, animations) while only suppressing color-related ones:

<ThemeProvider disableTransitionOnChange="background-color 0s, color 0s, border-color 0s, fill 0s, stroke 0s">
  {children}
</ThemeProvider>

The string is injected as transition: <value> !important on all elements for two animation frames, but only around a real DOM theme update.

Always follow system preference

Use followSystem to ignore any stored value and always apply the system preference. Useful for apps where you want the theme to stay in sync with the OS without letting users override it:

<ThemeProvider followSystem>
  {children}
</ThemeProvider>

Unlike defaultTheme="system", which applies the system preference only on first visit and then stores the resolved value, followSystem re-reads prefers-color-scheme on every mount and ignores the stored value entirely.

Disable storage

<ThemeProvider storage="none" defaultTheme="dark">
  {children}
</ThemeProvider>

Use this with your consent manager rather than giving the theme library control over consent:

<ThemeProvider storage={hasPreferenceConsent ? "localStorage" : "none"}>
  {children}
</ThemeProvider>

Remove the previous key when consent is revoked if your policy requires deletion; storage="none" guarantees no further reads or writes.

Observe storage failures

<ThemeProvider onStorageError={(error) => reportError(error)}>
  {children}
</ThemeProvider>

The selected theme still updates in memory and on the DOM when persistence is unavailable.

Meta theme-color

<ThemeProvider themeColor={{ light: "#ffffff", dark: "#0a0a0a" }}>
  {children}
</ThemeProvider>

Works with CSS variables too:

<ThemeProvider themeColor="var(--color-background)">
  {children}
</ThemeProvider>

CookieOptions

Options applied when writing the theme cookie. Used when storage is "cookie" or "hybrid".