Heroui React

1---2name: heroui-react3description: "HeroUI v3 React component library (Tailwind CSS v4 + React Aria). Use when building UIs with HeroUI — creating Buttons, Modals, Forms, Cards; installing @heroui/react; configuring dark/light themes with oklch variables; or fetching component docs. Keywords: HeroUI, Hero UI, heroui, @heroui/react, @heroui/styles."4metadata:5  author: heroui6  version: "3.0.1"7---8 9# HeroUI v3 React Development Guide10 11HeroUI v3 is a component library built on **Tailwind CSS v4** and **React Aria Components**, providing accessible, customizable UI components for React applications.12 13---14 15## Installation16 17```bash18curl -fsSL https://heroui.com/install | bash -s heroui-react19```20 21---22 23## CRITICAL: v3 Only - Ignore v2 Knowledge24 25**This guide is for HeroUI v3 ONLY.** Do NOT apply v2 patterns — the provider, styling, and component API all changed:26 27| Feature       | v2 (DO NOT USE)                   | v3 (USE THIS)                               |28| ------------- | --------------------------------- | ------------------------------------------- |29| Provider      | `<HeroUIProvider>` required       | **No Provider needed**                      |30| Animations    | `framer-motion` package           | CSS-based, no extra deps                    |31| Component API | Flat props: `<Card title="x">`    | Compound: `<Card><Card.Header>`             |32| Styling       | Tailwind v3 + `@heroui/theme`     | Tailwind v4 + `@heroui/styles`         	  |33| Packages      | `@heroui/system`, `@heroui/theme` | `@heroui/react`, `@heroui/styles` 		  |34 35```tsx36// DO NOT DO THIS - v2 pattern37import { HeroUIProvider } from "@heroui/react";38import { motion } from "framer-motion";39 40<HeroUIProvider>41	<Card title="Product" description="A great product" />42</HeroUIProvider>;43```44 45### CORRECT (v3 patterns)46 47```tsx48// DO THIS - v3 pattern (no provider, compound components)49import { Card } from "@heroui/react";50 51<Card>52	<Card.Header>53		<Card.Title>Product</Card.Title>54		<Card.Description>A great product</Card.Description>55	</Card.Header>56</Card>;57```58 59**Always fetch v3 docs before implementing.**60 61---62 63## Core Principles64 65- Semantic variants (`primary`, `secondary`, `tertiary`) over visual descriptions66- Composition over configuration (compound components)67- CSS variable-based theming with `oklch` color space68- BEM naming convention for predictable styling69 70---71 72## Accessing Documentation & Component Information73 74**For component details, examples, props, and implementation patterns, always fetch documentation:**75 76### Using Scripts77 78```bash79# List all available components80node scripts/list_components.mjs81 82# Get component documentation (MDX)83node scripts/get_component_docs.mjs Button84node scripts/get_component_docs.mjs Button Card TextField85 86# Get component source code87node scripts/get_source.mjs Button88 89# Get component CSS styles (BEM classes)90node scripts/get_styles.mjs Button91 92# Get theme variables93node scripts/get_theme.mjs94 95# Get non-component docs (guides, releases)96node scripts/get_docs.mjs /docs/react/getting-started/theming97```98 99### Direct MDX URLs100 101Component docs: `https://heroui.com/docs/react/components/{component-name}.mdx`102 103Examples:104 105- Button: `https://heroui.com/docs/react/components/button.mdx`106- Modal: `https://heroui.com/docs/react/components/modal.mdx`107- Form: `https://heroui.com/docs/react/components/form.mdx`108 109Getting started guides: `https://heroui.com/docs/react/getting-started/{topic}.mdx`110 111**Important:** Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.112 113---114 115## Installation Essentials116 117### Quick Install118 119```bash120npm i @heroui/styles @heroui/react tailwind-variants121```122 123### Framework Setup (Next.js App Router - Recommended)124 1251. **Install dependencies:**126 127```bash128npm i @heroui/styles @heroui/react tailwind-variants tailwindcss @tailwindcss/postcss postcss129```130 1312. **Create/update `app/globals.css`:**132 133```css134/* Tailwind CSS v4 - Must be first */135@import "tailwindcss";136 137/* HeroUI v3 styles - Must be after Tailwind */138@import "@heroui/styles";139```140 1413. **Import in `app/layout.tsx`:**142 143```tsx144import "./globals.css";145 146export default function RootLayout({147	children,148}: {149	children: React.ReactNode;150}) {151	return (152		<html lang="en" suppressHydrationWarning>153			<body>154				{/* No Provider needed in HeroUI v3! */}155				{children}156			</body>157		</html>158	);159}160```161 1624. **Configure PostCSS (`postcss.config.mjs`):**163 164```js165export default {166	plugins: {167		"@tailwindcss/postcss": {},168	},169};170```171 172### Critical Setup Requirements173 1741. **Tailwind CSS v4 is MANDATORY** - HeroUI v3 will NOT work with Tailwind CSS v31752. **Use Compound Components** - Components use compound structure (e.g., `Card.Header`, `Card.Content`)1763. **Use onPress, not onClick** - For better accessibility, use `onPress` event handlers1774. **Import Order Matters** - Always import Tailwind CSS before HeroUI styles178 179---180 181## Component Patterns182 183All components use the **compound pattern** shown above (dot-notation subcomponents like `Card.Header`, `Card.Content`). Don't flatten to props — always compose with subcomponents. Fetch component docs for complete anatomy and examples.184 185---186 187## Semantic Variants188 189HeroUI uses semantic naming to communicate functional intent:190 191| Variant     | Purpose                           | Usage          |192| ----------- | --------------------------------- | -------------- |193| `primary`   | Main action to move forward       | 1 per context  |194| `secondary` | Alternative actions               | Multiple       |195| `tertiary`  | Dismissive actions (cancel, skip) | Sparingly      |196| `danger`    | Destructive actions               | When needed    |197| `ghost`     | Low-emphasis actions              | Minimal weight |198| `outline`   | Secondary actions                 | Bordered style |199 200**Don't use raw colors** - semantic variants adapt to themes and accessibility.201 202---203 204## Theming205 206HeroUI v3 uses CSS variables with `oklch` color space:207 208```css209:root {210	--accent: oklch(0.6204 0.195 253.83);211	--accent-foreground: var(--snow);212	--background: oklch(0.9702 0 0);213	--foreground: var(--eclipse);214}215```216 217**Get current theme variables:**218 219```bash220node scripts/get_theme.mjs221```222 223**Color naming:**224 225- Without suffix = background (e.g., `--accent`)226- With `-foreground` = text color (e.g., `--accent-foreground`)227 228**Theme switching:**229 230```html231<html class="dark" data-theme="dark"></html>232```233 234For detailed theming, fetch: `https://heroui.com/docs/react/getting-started/theming.mdx`