heroui-react

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

curl -fsSL https://heroui.com/install | bash -s heroui-react

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:

// DO NOT DO THIS - v2 pattern
import { HeroUIProvider } from "@heroui/react";

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:

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