Skip to content

Next.js

Set up themes in a Next.js App Router application.

Install

npm install uitheme-web@latest

Create a client provider

app/providers.tsx
'use client';

import { NextUIThemeProvider } from 'uitheme-web/next';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <NextUIThemeProvider defaultTheme="system">{children}</NextUIThemeProvider>
  );
}

Wrap your root layout

Keep the layout as a Server Component. The provider includes the script that applies the saved appearance before hydration.

app/layout.tsx
import './globals.css';
import { Providers } from './providers';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <Providers>{children}</Providers>
      </body>
    </html>
  );
}

Keep theme hooks and interactive controls in Client Components. Use uitheme-web/next/server when you need server-safe bootstrap helpers. Do not import browser hooks into server code.

Add a control

Use the React hook example, or install a Theme Toggle. Set up Tailwind and palette styles before installing styled controls.

Check the first page load, saved preferences after reload, and system appearance changes. If your site uses a Content Security Policy, configure its nonce through the provider's supported options.

Example

Open the complete Next.js example. Start with app/providers.tsx and app/layout.tsx.