Framework Guide

Next.js

Complete guide to installing tweakcn/theme-picker themes in your Next.js application. Works with both App Router and Pages Router.

Prerequisites

Next.js 13.4+ (App Router) or Next.js 12+ (Pages Router)

shadcn/ui initialized in your project

Tailwind CSS configured

Flash Prevention Setup

tweakcn/theme-picker uses data-theme attributes. To prevent flash on load, you need:

:root fallback in CSS with your default theme colors
Inline script in <head> to set data-theme before render
Optional: @media (prefers-color-scheme) for system preference support

Installation

Install the theme system

Run this single command to install the complete theme system. This includes all 42+ themes, the ThemeProvider component, theme CSS, and configures next-themes automatically.

$ pnpm dlx shadcn@latest add https://tweakcn-picker.vercel.app/r/nextjs/theme-system.json

This will modify your project

The CLI will create/overwrite your ThemeProvider, add theme CSS files, and update your globals.css. Make sure to commit your changes first!

Set up your root layout

Add the ThemeProvider and flash prevention script to your root layout. The inline script in <head> runs before React hydrates, preventing any flash of unstyled content.

app/layout.tsxtsx

1import { ThemeProvider } from "@/components/providers/theme-provider"
2
3export default function RootLayout({
4  children,
5}: {
6  children: React.ReactNode
7}) {
8  return (
9    <html lang="en" suppressHydrationWarning>
10      <head>
11        {/* Flash Prevention: Apply theme before render */}
12        <script
13          dangerouslySetInnerHTML={{
14            __html: `
15              (function() {
16                const stored = localStorage.getItem('theme');
17                if (stored) {
18                  document.documentElement.setAttribute('data-theme', stored);
19                } else {
20                  const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
21                  document.documentElement.setAttribute('data-theme', isDark ? 'default-dark' : 'default-light');
22                }
23              })();
24            `,
25          }}
26        />
27      </head>
28      <body>
29        <ThemeProvider
30          attribute="data-theme"
31          defaultTheme="default-dark"
32          enableSystem={false}
33          disableTransitionOnChange
34        >
35          {children}
36        </ThemeProvider>
37      </body>
38    </html>
39  )
40}

Why the inline script?

The script runs synchronously before any CSS or React loads, setting data-theme immediately. This prevents flash because CSS variables are applied before the first paint. Add suppressHydrationWarning to prevent hydration warnings.

Import theme styles

The CLI adds the theme imports to your globals.css automatically. Verify it looks like this:

app/globals.csscss

1@import "tailwindcss";
2
3/* tweakcn/theme-picker theme imports */
4@import "../styles/index.css";
5
6@layer base {
7  * {
8    @apply border-border;
9  }
10  body {
11    @apply bg-background text-foreground;
12  }
13}

Use the included ThemeSwitcher

The CLI installs a complete ThemeSwitcher component that lets users switch between all 42+ themes and toggle light/dark modes. Import and use it anywhere in your app:

Using the ThemeSwitchertsx

1import { ThemeSwitcher } from "@/components/theme-switcher"
2
3export function Header() {
4  return (
5    <header>
6      <nav>{/* ... */}</nav>
7      <ThemeSwitcher />
8    </header>
9  )
10}

The ThemeSwitcher includes a dropdown menu with all available themes, light/dark mode toggle, and displays the current theme with a color indicator.

Install Individual Themes

$ pnpm dlx shadcn@latest add https://tweakcn-picker.vercel.app/r/theme-catppuccin.json

Replace theme-catppuccin with any theme: theme-claude, theme-vercel, theme-cyberpunk, etc.

Still need the provider

Individual theme installation only adds the CSS. You'll still need to set up the ThemeProvider and imports as shown above.

ThemeProvider Configuration

The ThemeProvider accepts several props to customize behavior:

Prop	Type	Description
attribute	string	HTML attribute to apply theme. Use `"data-theme"` for tweakcn/theme-picker.
defaultTheme	string	Default theme. Format: `"theme-name-light"` or `"theme-name-dark"`
themes	string[]	Array of available themes. Pre-configured with all tweakcn/theme-picker themes.
enableSystem	boolean	Whether to use system preference. Set to `false` for manual control.

Available Theme Values

Each theme has both light and dark variants. Use these values with setTheme():

[theme-name]-light
[theme-name]-dark
Examples:
- default-light / default-dark
- catppuccin-light / catppuccin-dark
- claude-light / claude-dark
- vercel-light / vercel-dark
- cyberpunk-light / cyberpunk-dark