Skill v1.0.1

currentAutomated scan81/100

heroui-inc/heroui/heroui-react

10 files

──Details

PublishedMay 22, 2026 at 05:17 AM

Content Hashsha256:92a42da5bfc89635...

Git SHA86d06bc9e95f

Bump Typepatch

Compare with v1.0.0

──Files

Files (1 file, 6.4 KB)

SKILL.md6.4 KBactive

SKILL.md · 236 lines · 6.4 KB

version: "1.0.1" name: heroui-react description: "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." metadata: author: heroui version: "3.0.1"

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

bash

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:

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`

tsx

// DO NOT DO THIS - v2 pattern
import { HeroUIProvider } from "@heroui/react";
import { motion } from "framer-motion";
<HeroUIProvider>
	<Card title="Product" description="A great product" />
</HeroUIProvider>;

CORRECT (v3 patterns)

tsx

// DO THIS - v3 pattern (no provider, compound components)
import { Card } from "@heroui/react";
<Card>
	<Card.Header>
		<Card.Title>Product</Card.Title>
		<Card.Description>A great product</Card.Description>
	</Card.Header>
</Card>;

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

bash

# List all available components
node scripts/list_components.mjs
 
# Get component documentation (MDX)
node scripts/get_component_docs.mjs Button
node scripts/get_component_docs.mjs Button Card TextField
 
# Get component source code
node scripts/get_source.mjs Button
 
# Get component CSS styles (BEM classes)
node scripts/get_styles.mjs Button
 
# Get theme variables
node scripts/get_theme.mjs
 
# Get non-component docs (guides, releases)
node scripts/get_docs.mjs /docs/react/getting-started/theming

Direct MDX URLs

Component docs: https://heroui.com/docs/react/components/{component-name}.mdx

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: https://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

Quick Install

bash

npm i @heroui/styles @heroui/react tailwind-variants

Framework Setup (Next.js App Router - Recommended)

Install dependencies:

bash

npm i @heroui/styles @heroui/react tailwind-variants tailwindcss @tailwindcss/postcss postcss

Create/update `app/globals.css`:

css

/* Tailwind CSS v4 - Must be first */
@import "tailwindcss";
 
/* HeroUI v3 styles - Must be after Tailwind */
@import "@heroui/styles";

Import in `app/layout.tsx`:

tsx

import "./globals.css";
export default function RootLayout({
	children,
}: {
	children: React.ReactNode;
}) {
	return (
		<html lang="en" suppressHydrationWarning>
			<body>
				{/* No Provider needed in HeroUI v3! */}
				{children}
			</body>
		</html>
	);
}

Configure PostCSS (`postcss.config.mjs`):

export default {
	plugins: {
		"@tailwindcss/postcss": {},
	},
};

Critical Setup Requirements

Tailwind CSS v4 is MANDATORY - HeroUI v3 will NOT work with Tailwind CSS v3
Use Compound Components - Components use compound structure (e.g., Card.Header, Card.Content)
Use onPress, not onClick - For better accessibility, use onPress event handlers
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:

css

:root {
	--accent: oklch(0.6204 0.195 253.83);
	--accent-foreground: var(--snow);
	--background: oklch(0.9702 0 0);
	--foreground: var(--eclipse);
}

Get current theme variables:

bash

node scripts/get_theme.mjs

Color naming:

Without suffix = background (e.g., --accent)
With -foreground = text color (e.g., --accent-foreground)

Theme switching:

html

<html class="dark" data-theme="dark"></html>

For detailed theming, fetch: https://heroui.com/docs/react/getting-started/theming.mdx

← v1.0.0 All versions