tweakcn/theme-picker
Framework Guide

Astro

Complete guide to installing tweakcn/theme-picker themes in your Astro project with React islands. Uses inline scripts for instant theme application.

Prerequisites

Astro 3.0+ with React integration
shadcn/ui initialized in your project
Tailwind CSS configured

Keep :root and .dark as fallbacks

tweakcn/theme-picker themes use data-theme attributes. Keep your :root and .dark variable blocks as fallbacks to prevent flash of unstyled content before the theme loads.

Installation

Install the theme system

Run this single command to install the complete theme system for Astro. This includes all 42+ themes, the theme scripts, and all theme CSS.

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

Create an inline theme script

Add this inline script to your layout to apply the theme before the page renders:

src/layouts/Layout.astroastro
1---
2import '../styles/globals.css'
3---
4
5<html lang="en">
6  <head>
7    <meta charset="UTF-8" />
8    <meta name="viewport" content="width=device-width" />
9    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
10    <title>My Astro Site</title>
11    <!-- Flash Prevention: Apply theme before render -->
12    <script is:inline>
13      (function() {
14        var stored = localStorage.getItem("tweakcn-theme");
15        if (stored) {
16          document.documentElement.setAttribute("data-theme", stored);
17        } else {
18          // Respect system preference for first-time visitors
19          var isDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
20          document.documentElement.setAttribute("data-theme", isDark ? "default-dark" : "default-light");
21        }
22      })();
23    </script>
24  </head>
25  <body>
26    <slot />
27  </body>
28</html>

Use the included ThemeSwitcher

The CLI installs a complete ThemeSwitcher component. Use it with the client:load directive:

src/pages/index.astroastro
1---
2import Layout from '../layouts/Layout.astro';
3import { ThemeSwitcher } from '@/components/theme-switcher';
4---
5
6<Layout>
7  <main>
8    <h1>Welcome to Astro</h1>
9    <ThemeSwitcher client:load />
10  </main>
11</Layout>

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, etc.

Troubleshooting