npm package: @nuvia/components
Description: React UI components for Nuvia applications, built with Radix UI primitives and Tailwind CSS v4.
Latest version: 1.9.0

# @nuvia/components

React UI components for Nuvia applications, built with Radix UI primitives and Tailwind CSS v4.

## Installation

```bash
pnpm add @nuvia/components @nuvia/tailwind-config
```

## Setup

### Vite Projects

```bash
pnpm add -D @tailwindcss/vite
```

```typescript
// vite.config.ts
import tailwindcss from "@tailwindcss/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [react(), tailwindcss()],
});
```

### Next.js / Other Projects

```bash
pnpm add -D @tailwindcss/postcss
```

```javascript
// postcss.config.mjs
/** @type {import('postcss-load-config').Config} */
const config = {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};

export default config;
```

### Tailwind Config (All Projects)

```typescript
// tailwind.config.ts
import { config } from "@nuvia/tailwind-config";
import type { Config } from "tailwindcss";

export default {
  ...config,
  content: [
    "./src/**/*.{ts,tsx}",  // or "./app/**/*.{ts,tsx}" for Next.js
    "./node_modules/@nuvia/components/**/*.{js,ts,jsx,tsx}",
  ],
} satisfies Config;
```

### CSS Entry Point (All Projects)

```css
/* globals.css or index.css */
@import "tailwindcss";
@import "@nuvia/components/styles/globals.css";

@config "./tailwind.config.ts";
```

> **Important:** `@import` must come before `@config` in Tailwind v4.

### Add Providers

```tsx
import { ThemeProvider } from "@nuvia/components/providers/theme";
import { TooltipProvider } from "@nuvia/components/ui/tooltip";
import { Toaster } from "@nuvia/components/ui/sonner";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ThemeProvider defaultTheme="system" storageKey="app-theme">
      <TooltipProvider>
        {children}
        <Toaster />
      </TooltipProvider>
    </ThemeProvider>
  );
}
```

## Usage

```tsx
// Import from main entry
import { Button, Card, Dialog } from "@nuvia/components";

// Or import from specific paths (better tree-shaking)
import { Button } from "@nuvia/components/ui/button";
import { Card } from "@nuvia/components/ui/card";
```

## What's Included

When you import `@nuvia/components/styles/globals.css`, you get:

- **Tailwind v4 theme registration** — All design tokens as utility classes (`bg-muted`, `text-primary`, etc.)
- **CSS variables** — Full color palette with light/dark theme support
- **Dark mode** — Automatic via `@custom-variant dark`
- **Base styles** — Body defaults, border colors, font family
- **Utility classes** — `.flex-center`, gradients, typography tokens

## Components

| Category | Components |
|----------|------------|
| **Layout** | Card, Separator, Resizable, Scroll Area, Aspect Ratio |
| **Navigation** | Breadcrumb, Navigation Menu, Pagination, Sidebar, Tabs |
| **Forms** | Button, Checkbox, Input, Radio Group, Select, Slider, Switch, Textarea, Form, Combobox |
| **Feedback** | Alert, Progress, Skeleton, Spinner, Toast/Sonner |
| **Overlay** | Dialog, Drawer, Sheet, Popover, Tooltip, Hover Card, Alert Dialog |
| **Data Display** | Avatar, Badge, Chip, Table, Calendar, Chart, Carousel |
| **Menu** | Dropdown Menu, Context Menu, Menubar, Command |
| **Other** | Accordion, Collapsible, Toggle, Logo |

## Theming

Toggle between light and dark themes by adding/removing the `dark` class on the root element. The `ThemeProvider` handles this automatically based on user preference.

```tsx
// Manual theme toggle
document.documentElement.classList.toggle("dark");
```

## Peer Dependencies

- `react` ^18.0.0 || ^19.0.0
- `react-dom` ^18.0.0 || ^19.0.0