HeroUI v3 React Development Guide
HeroUI v3 is a component library built on Tailwind CSS v4 and React Aria Components, providing accessible, customizable UI components for React applications.
CRITICAL: v3 Only - Ignore v2 Knowledge
This guide is for HeroUI v3 ONLY. Do NOT use any prior knowledge of HeroUI v2.
What Changed in v3
| Feature | v2 (DO NOT USE) | v3 (USE THIS) |
|---|---|---|
| Provider | <HeroUIProvider> required | No Provider needed |
| Animations | framer-motion package | CSS-based, no extra deps |
| Component API | Flat props: <Card title="x"> | Compound: <Card><Card.Header> |
| Styling | Tailwind v3 + @heroui/theme | Tailwind v4 + @heroui/styles@beta |
| Packages | @heroui/system, @heroui/theme | @heroui/react@beta, @heroui/styles@beta |
WRONG (v2 patterns)
tsx1// DO NOT DO THIS - v2 pattern 2import { HeroUIProvider } from "@heroui/react"; 3import { motion } from "framer-motion"; 4 5<HeroUIProvider> 6 <Card title="Product" description="A great product" /> 7</HeroUIProvider>;
CORRECT (v3 patterns)
tsx1// DO THIS - v3 pattern (no provider, compound components) 2import { Card } from "@heroui/react@beta"; 3 4<Card> 5 <Card.Header> 6 <Card.Title>Product</Card.Title> 7 <Card.Description>A great product</Card.Description> 8 </Card.Header> 9</Card>;
Always fetch v3 docs before implementing. Do not assume v2 patterns work.
Core Principles
- Semantic variants (
primary,secondary,tertiary) over visual descriptions - Composition over configuration (compound components)
- CSS variable-based theming with
oklchcolor space - BEM naming convention for predictable styling
Accessing Documentation & Component Information
For component details, examples, props, and implementation patterns, always fetch documentation:
Using Scripts
bash1# List all available components 2node scripts/list_components.mjs 3 4# Get component documentation (MDX) 5node scripts/get_component_docs.mjs Button 6node scripts/get_component_docs.mjs Button Card TextField 7 8# Get component source code 9node scripts/get_source.mjs Button 10 11# Get component CSS styles (BEM classes) 12node scripts/get_styles.mjs Button 13 14# Get theme variables 15node scripts/get_theme.mjs 16 17# Get non-component docs (guides, releases) 18node scripts/get_docs.mjs /docs/react/getting-started/theming
Direct MDX URLs
Component docs: https://v3.heroui.com/docs/react/components/{component-name}.mdx
Examples:
- Button:
https://v3.heroui.com/docs/react/components/button.mdx - Modal:
https://v3.heroui.com/docs/react/components/modal.mdx - Form:
https://v3.heroui.com/docs/react/components/form.mdx
Getting started guides: https://v3.heroui.com/docs/react/getting-started/{topic}.mdx
Important: Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references.
Installation Essentials
CRITICAL: HeroUI v3 is currently in BETA. Always use @beta tag when installing packages.
Quick Install
bash1npm i @heroui/styles@beta @heroui/react@beta tailwind-variants
Framework Setup (Next.js App Router - Recommended)
- Install dependencies:
bash1npm i @heroui/styles@beta @heroui/react@beta tailwind-variants tailwindcss @tailwindcss/postcss postcss
- Create/update
app/globals.css:
css1/* Tailwind CSS v4 - Must be first */ 2@import "tailwindcss"; 3 4/* HeroUI v3 styles - Must be after Tailwind */ 5@import "@heroui/styles";
- Import in
app/layout.tsx:
tsx1import "./globals.css"; 2 3export default function RootLayout({ 4 children, 5}: { 6 children: React.ReactNode; 7}) { 8 return ( 9 <html lang="en" suppressHydrationWarning> 10 <body> 11 {/* No Provider needed in HeroUI v3! */} 12 {children} 13 </body> 14 </html> 15 ); 16}
- Configure PostCSS (
postcss.config.mjs):
js1export default { 2 plugins: { 3 "@tailwindcss/postcss": {}, 4 }, 5};
Critical Setup Requirements
- Tailwind CSS v4 is MANDATORY - HeroUI v3 will NOT work with Tailwind CSS v3
- No Provider Required - Unlike HeroUI v2, v3 components work directly without a Provider
- Use Compound Components - Components use compound structure (e.g.,
Card.Header,Card.Content) - Use onPress, not onClick - For better accessibility, use
onPressevent handlers - Import Order Matters - Always import Tailwind CSS before HeroUI styles
Component Patterns
HeroUI v3 uses compound component patterns. Each component has subcomponents accessed via dot notation.
Example - Card:
tsx1<Card> 2 <Card.Header> 3 <Card.Title>Title</Card.Title> 4 <Card.Description>Description</Card.Description> 5 </Card.Header> 6 <Card.Content>{/* Content */}</Card.Content> 7 <Card.Footer>{/* Actions */}</Card.Footer> 8</Card>
Key Points:
- Always use compound structure - don't flatten to props
- Subcomponents are accessed via dot notation (e.g.,
Card.Header) - Each subcomponent may have its own props
- Fetch component docs for complete anatomy and examples
Semantic Variants
HeroUI uses semantic naming to communicate functional intent:
| Variant | Purpose | Usage |
|---|---|---|
primary | Main action to move forward | 1 per context |
secondary | Alternative actions | Multiple |
tertiary | Dismissive actions (cancel, skip) | Sparingly |
danger | Destructive actions | When needed |
ghost | Low-emphasis actions | Minimal weight |
outline | Secondary actions | Bordered style |
Don't use raw colors - semantic variants adapt to themes and accessibility.
Theming
HeroUI v3 uses CSS variables with oklch color space:
css1:root { 2 --accent: oklch(0.6204 0.195 253.83); 3 --accent-foreground: var(--snow); 4 --background: oklch(0.9702 0 0); 5 --foreground: var(--eclipse); 6}
Get current theme variables:
bash1node scripts/get_theme.mjs
Color naming:
- Without suffix = background (e.g.,
--accent) - With
-foreground= text color (e.g.,--accent-foreground)
Theme switching:
html1<html class="dark" data-theme="dark"></html>
For detailed theming, fetch: https://v3.heroui.com/docs/react/getting-started/theming.mdx
