> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/BankkRoll/tweakcn-theme-picker/llms.txt
> Use this file to discover all available pages before exploring further.
# Astro Installation
> Install and configure tweakcn themes in your Astro application
## Prerequisites
Before installing themes, ensure you have shadcn/ui set up in your Astro project with React integration. If you haven't already:
```bash theme={null}
npx astro add react
```
```bash theme={null}
npx shadcn@latest init
```
The theme system requires these shadcn/ui components:
```bash theme={null}
npx shadcn@latest add dropdown-menu button
```
## Installation
Install the complete theme system with all 40+ themes:
```bash npm theme={null}
npx shadcn@latest add https://tweakcn-picker.vercel.app/r/astro/theme-system
```
```bash yarn theme={null}
yarn dlx shadcn@latest add https://tweakcn-picker.vercel.app/r/astro/theme-system
```
```bash pnpm theme={null}
pnpm dlx shadcn@latest add https://tweakcn-picker.vercel.app/r/astro/theme-system
```
This installs:
* `lib/themes-config.ts` - Theme configuration and metadata
* `components/theme-script.astro` - Inline script for preventing FOUC
* `components/mode-toggle.tsx` - React component for theme switching
* `styles/themes/*.css` - All 40+ theme CSS files
Add the theme script component in the `` of your base layout to prevent flash of unstyled content (FOUC):
```astro src/layouts/Layout.astro theme={null}
---
import ThemeScript from "@/components/theme-script.astro";
import "@/styles/themes/index.css";
---
My Astro Site
```
The `ThemeScript` component must be placed in the `` tag to work correctly and prevent FOUC.
Import and use the ModeToggle component in any `.astro` or `.tsx` file:
```astro src/components/Header.astro theme={null}
---
import { ModeToggle } from "@/components/mode-toggle";
---
```
The `client:load` directive is required for React components to be interactive in Astro.
## How it works
The Astro adapter uses an **inline script** for theme management to avoid hydration issues:
Located at `components/theme-script.astro`:
```astro theme={null}
```
The `is:inline` directive ensures the script runs before any other JavaScript, preventing FOUC.
Located at `components/mode-toggle.tsx`:
```tsx theme={null}
import * as React from "react";
import { Moon, Sun } from "lucide-react";
import { Button } from "@/components/ui/button";
const STORAGE_KEY = "tweakcn-theme";
const DEFAULT_THEME = "default-dark";
export function ModeToggle() {
const [theme, setThemeState] = React.useState(DEFAULT_THEME);
React.useEffect(() => {
// Get initial theme
const currentTheme =
document.documentElement.getAttribute("data-theme") ||
localStorage.getItem(STORAGE_KEY) ||
DEFAULT_THEME;
setThemeState(currentTheme);
// Listen for theme changes
const handleThemeChange = (e: CustomEvent) => {
setThemeState(e.detail);
};
window.addEventListener("theme-change", handleThemeChange as EventListener);
return () => {
window.removeEventListener("theme-change", handleThemeChange as EventListener);
};
}, []);
const setTheme = (newTheme: string) => {
setThemeState(newTheme);
if (typeof window !== "undefined" && window.setTheme) {
window.setTheme(newTheme);
}
};
const isDark = theme.endsWith("-dark");
const colorTheme = theme.replace("-light", "").replace("-dark", "");
return (
);
}
```
The theme script includes multi-tab synchronization using the Storage API:
```javascript theme={null}
window.addEventListener("storage", (e) => {
if (e.key === STORAGE_KEY && e.newValue) {
applyTheme(e.newValue);
}
});
```
When you change the theme in one tab, all other tabs automatically update.
## Adding individual themes
To install specific themes instead of all 40+:
```bash Catppuccin theme theme={null}
npx shadcn@latest add https://tweakcn-picker.vercel.app/r/theme-catppuccin
```
```bash Multiple themes theme={null}
npx shadcn@latest add https://tweakcn-picker.vercel.app/r/theme-catppuccin
npx shadcn@latest add https://tweakcn-picker.vercel.app/r/theme-supabase
npx shadcn@latest add https://tweakcn-picker.vercel.app/r/theme-nature
```
Then import only the themes you need:
```css src/styles/themes/index.css theme={null}
@import "./catppuccin.css";
@import "./supabase.css";
@import "./nature.css";
```
## Customizing themes
All theme CSS files are in `src/styles/themes/`. Each theme defines CSS variables:
```css src/styles/themes/supabase.css theme={null}
[data-theme="supabase-light"] {
--background: oklch(0.99 0 0);
--foreground: oklch(0.25 0.02 267.08);
--primary: oklch(0.83 0.13 160.91);
--primary-foreground: oklch(0.20 0.03 267.08);
/* ... more variables */
}
[data-theme="supabase-dark"] {
--background: oklch(0.13 0.01 264.53);
--foreground: oklch(0.93 0.01 264.53);
--primary: oklch(0.44 0.1 156.76);
--primary-foreground: oklch(0.93 0.01 264.53);
/* ... more variables */
}
```
Edit these files to customize colors, borders, shadows, and more.
## TypeScript usage
You can programmatically change themes using the global `setTheme` function:
```typescript theme={null}
// In any TypeScript file
if (typeof window !== "undefined" && window.setTheme) {
window.setTheme("supabase-dark");
}
```
Add TypeScript declarations for the global function:
```typescript src/env.d.ts theme={null}
///
declare global {
interface Window {
setTheme: (theme: string) => void;
}
}
export {};
```
## Astro configuration
Ensure your `astro.config.mjs` includes the React integration:
```javascript astro.config.mjs theme={null}
import { defineConfig } from 'astro/config';
import react from '@astrojs/react';
export default defineConfig({
integrations: [react()],
});
```
## Client directives
When using React components in Astro, choose the appropriate client directive:
* `client:load` - Hydrates immediately on page load (recommended for theme toggle)
* `client:idle` - Hydrates when the main thread is free
* `client:visible` - Hydrates when the component enters the viewport
```astro theme={null}
```
## Next steps
Explore all 40+ available themes
Preview themes in real-time
Install themes in Next.js
Install themes in Vite React