On this page
Astro Setup
Set up Ninna UI in Astro with React integration and Tailwind CSS v4. Hydrate interactive React islands while keeping static content server-rendered.
Start with the CLI
Create a configured Ninna UI project, or follow the manual setup below for an existing application.
npx @ninna-ui/cli@latest init my-app --template astro --preset oceancd my-appnpm run devUse Node.js 24 LTS. Omit --template for the framework prompt, or change --preset to select another theme. This command installs the published CLI; see the installation guide for release status, flags, and package-manager instructions.
Prerequisites
- Node.js 24 LTS recommended
- Astro 7 with React 19
@astrojs/reactintegration- Tailwind CSS v4 via
@tailwindcss/vite
Create Project
Skip this step if you already have an Astro project.
npm create astro@latest my-appcd my-appInstall Ninna UI
Install the component packages you need. All packages auto-install @ninna-ui/core.
pnpm add @ninna-ui/primitives@latest @ninna-ui/feedback@latest @ninna-ui/forms@latest @ninna-ui/layout@latest @astrojs/react react@^19 react-dom@^19pnpm add -D @types/react@^19 @types/react-dom@^19You can also install additional packages later - e.g. @ninna-ui/overlays, @ninna-ui/navigation, @ninna-ui/data-display.
Install Tailwind CSS
Astro uses Vite under the hood - use the @tailwindcss/vite plugin for the fastest builds.
pnpm add -D tailwindcss @tailwindcss/viteConfigure Astro
Add the React integration and Tailwind CSS plugin to your Astro config.
// astro.config.mjsimport { defineConfig } from 'astro/config';import react from '@astrojs/react';import tailwindcss from '@tailwindcss/vite';
export default defineConfig({ integrations: [react()], vite: { plugins: [tailwindcss()], },});CSS Setup
Create your global styles file.
Create src/styles/globals.css:
@import "tailwindcss";@import "@ninna-ui/core/theme/presets/default.css";
/* Enable dark mode support */@variant dark (&:is(.dark *));Layout Setup
Create a base layout that imports your styles and sets the data-theme attribute.
---// src/layouts/Layout.astroimport "../styles/globals.css";
interface Props { title: string;}const { title } = Astro.props;---<!doctype html><html lang="en" data-theme="default"> <head> <meta charset="UTF-8" /> <meta name="description" content="My Ninna UI + Astro app" /> <meta name="viewport" content="width=device-width" /> <title>{title}</title> </head> <body class="min-h-screen bg-base-50 text-base-content antialiased"> <slot /> </body></html>The data-theme attribute must match the preset name from your CSS import.
Your First Component
Create a React component and use it in an Astro page.
React components must be rendered with a client: directive to be interactive:
// src/components/Hero.tsximport { useState } from "react";import { Button, Heading, Text } from "@ninna-ui/primitives";
export function Hero() { const [count, setCount] = useState(0); return ( <div className="p-8 text-center"> <Heading as="h1" size="3xl">Hello Ninna UI + Astro</Heading> <Text className="text-base-content/70 mt-2">It works!</Text> <Button color="primary" className="mt-4" onClick={() => setCount(count + 1)}> Clicked {count} times </Button> </div> );}---// src/pages/index.astroimport Layout from '../layouts/Layout.astro';import { Hero } from '../components/Hero';---<Layout title="My App"> <Hero client:load /></Layout>Use client:load for interactive components, or client:idle / client:visible for deferred hydration.
Hydration and dependencies
Use React islands for interactions and let Astro select its compatible Vite version.
Components without a client: directive render static HTML. Keep the interactive form, tabs, or dialog inside a hydrated React island so related components share their React context. The initial state must match the server-rendered HTML. Use browser APIs in effects or event handlers after hydration.
Remove old Vite 7 overrides when upgrading to the CLI 0.7 starter. Install compatible Astro and @astrojs/react releases together; do not override Astro's bundler just to silence a peer dependency warning. Astro React components do not need Next.js's "use client" directive.
Theme Presets
Switch themes by changing the CSS import and the data-theme attribute.
/* 1. Change the CSS import in src/styles/globals.css */@import "@ninna-ui/core/theme/presets/default.css"; /* Electric purple */@import "@ninna-ui/core/theme/presets/ocean.css"; /* Blue + cyan */@import "@ninna-ui/core/theme/presets/sunset.css"; /* Orange + rose */@import "@ninna-ui/core/theme/presets/forest.css"; /* Green + amber */@import "@ninna-ui/core/theme/presets/minimal.css"; /* Monochrome */
/* 2. Update data-theme in src/layouts/Layout.astro *//* <html lang="en" data-theme="ocean"> */Dark mode works automatically via prefers-color-scheme or by adding the .dark class to <html>.