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, @h

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. Installation CRITICAL: v3 Only Ignore v2 Knowledge This guide is for HeroUI v3 ONLY. Do NOT apply v2 patterns — the provider, styling, and component API all changed: 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 Packages @heroui/system , @heroui/theme @heroui/react , @heroui/styles CORRECT (v3 patterns) Always fetch v3 docs before implementing. Core Principles Semantic variants ( primary , secondary , tertiary ) over visual descriptions Composition over configuration (compound components) CSS variable based theming with oklch color space BEM naming convention for predictable styling Accessing Documentation & Component Information For component details, examples, props, and implementation patterns, always fetch documentation: Using Scripts Direct MDX URLs Component docs: fetch .mdx with a concrete kebab case slug. Run node scripts/list components.mjs when the slug is unknown, and never fetch a URL that still contains a placeholder. Examples: Button: https://heroui.com/docs/react/components/button.mdx Modal: https://heroui.com/docs/react/components/modal.mdx Form: https://heroui.com/docs/react/components/form.mdx Getting started guides: use a concrete topic URL such as https://heroui.com/docs/react/getting started/quick start.mdx . Important: Always fetch component docs before implementing. The MDX docs include complete examples, props, anatomy, and API references. Installation Essentials Quick Install Framework Setup (Next.js App Router Recommended) 1. Install dependencies: 2. Create/update app/globals.css : 3. Import in app/layout.tsx : 4. Configure PostCSS ( postcss.config.mjs ): Critical Setup Requirements 1. Tailwind CSS v4 is MANDATORY HeroUI v3 will NOT work with Tailwind CSS v3 2. Use Compound Components Components use compound structure (e.g., Card.Header , Card.Content ) 3. Use onPress, not onClick For better accessibility, use onPress event handlers 4. Import Order Matters Always import Tailwind CSS before HeroUI styles Component Patterns All 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. 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: Get current theme variables: Color naming: Without suffix = background (e.g., accent ) With foreground = text color (e.g., accent foreground ) Theme switching: For detailed theming, fetch: https://heroui.com/docs/react/getting started/theming.mdx

heroui-react