Skip to main content
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 ocean
cd my-app
npm run dev

Use 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/react integration
  • Tailwind CSS v4 via @tailwindcss/vite

Create Project

Skip this step if you already have an Astro project.

npm create astro@latest my-app
cd my-app

Install 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@^19
pnpm add -D @types/react@^19 @types/react-dom@^19

You 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/vite

Configure Astro

Add the React integration and Tailwind CSS plugin to your Astro config.

// astro.config.mjs
import { 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.astro
import "../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.tsx
import { 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.astro
import 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>.