Skip to main content

​
Installation

The tweakcn Theme Picker is distributed as a shadcn/ui registry package. Installation is a two-step process:
  1. Install the theme system (components + config)
  2. Add individual themes you want to use

​
Prerequisites

Before installing, make sure you have:
  • A project with shadcn/ui configured
  • Node.js 16+ installed
  • A package manager (npm, yarn, or pnpm)
If you haven’t set up shadcn/ui yet, follow the shadcn/ui installation guide for your framework first.

​
Framework-specific guides

Choose your framework to see detailed installation instructions:

Next.js

Install for Next.js App Router with next-themes

Vite

Set up in Vite + React projects

Astro

Configure for Astro with React islands

Remix

Install with Remix SSR support

​
Quick install

For a quick overview, here’s the basic installation flow:
1

Install theme system

Run the framework-specific command to install the theme system:
npx shadcn@latest add https://tweakcn-picker.vercel.app/r/nextjs/theme-system.json
This installs:
  • ThemeProvider component
  • ThemeSwitcher component (or ModeToggle for Astro/Remix)
  • themes-config.ts configuration file
  • Base CSS files and all 43 theme stylesheets
2

Wrap your app with ThemeProvider

Add the ThemeProvider to your root layout or app entry point:
import { ThemeProvider } from "@/components/theme-provider";

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}
3

Add the theme switcher

Place the ThemeSwitcher component in your header or navigation:
import { ThemeSwitcher } from "@/components/theme-switcher";

export function Header() {
  return (
    <header>
      <nav>{/* Your navigation */}</nav>
      <ThemeSwitcher />
    </header>
  );
}
4

Add individual themes (optional)

The theme system includes all 43 themes by default. To add a specific theme individually:
npx shadcn@latest add https://tweakcn-picker.vercel.app/r/theme-catppuccin.json
Replace catppuccin with any theme name (e.g., cyberpunk, vercel, github).

​
What gets installed

The theme system installation adds these files to your project:

​
Components

  • components/theme-provider.tsx - React context provider for theme state
  • components/theme-switcher.tsx - Dropdown UI for selecting themes (Next.js/Vite)
  • components/mode-toggle.tsx - Light/dark mode toggle (Astro/Remix)

​
Configuration

  • lib/themes-config.ts - Theme metadata and configuration
  • lib/sessions.server.ts - Server-side session storage (Remix only)

​
Styles

  • styles/themes/index.css - Base theme CSS and imports
  • styles/themes/{theme-name}.css - Individual theme stylesheets (43 files)

​
Actions (Remix only)

  • app/routes/action.set-theme.ts - Server action for theme persistence

​
Dependency installation

The shadcn CLI automatically installs required dependencies:
  • Next.js/Vite: next-themes for theme management
  • Remix: remix-themes for SSR-compatible theming
  • All frameworks: shadcn/ui components (dropdown-menu, scroll-area, button)

​
Next steps

Next.js guide

Detailed Next.js installation with examples

Vite guide

Complete Vite setup instructions

Theme Provider

Configure the ThemeProvider component

Browse themes

Explore all 43 available themes

​
Troubleshooting

Make sure you’ve imported the theme CSS in your root layout:
import "@/styles/themes/index.css";
For Next.js, this should be in app/layout.tsx. For Vite, add it to src/main.tsx.
Verify that:
  1. Your <html> tag has suppressHydrationWarning attribute
  2. The ThemeProvider wraps your entire app
  3. You’re using the correct theme naming format: {name}-light or {name}-dark
Install the shadcn CLI globally:
npm install -g shadcn
Make sure your tsconfig.json includes the path aliases:
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}
For Next.js, use ["./app/*", "./components/*"] if needed.

Build docs developers (and LLMs) love

Get started for freeTalk to us