/heroui-react
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,
$ npx -y skills add heroui-inc/heroui --skill heroui-react --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/heroui-react
Context preview
The summary Claude sees to decide when to auto-load this skill.
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,
SKILL.md
heroui-react.SKILL.mdname: 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
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` |
// 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)
// 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
# 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
npm i @heroui/styles @heroui/react tailwind-variants
Framework Setup (Next.js App Router - Recommended)
1. **Install dependencies:**
npm i @heroui/styles @heroui/react tailwind-variants tailwindcss @tailwindcss/postcss postcss
2. **Create/update `app/globals.css`:**
/* Tailwind CSS v4 - Must be first */
@import "tailwindcss";
/* HeroUI v3 styles - Must be after Tailwind */
@import "@heroui/styles";
3. **Import in `app/layout.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>
);
}4. **Configure PostCSS (`postcss.config.mjs`):**
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};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:
:root {
--Read more
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
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` |
// 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)
// 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
# 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
npm i @heroui/styles @heroui/react tailwind-variants
Framework Setup (Next.js App Router - Recommended)
1. **Install dependencies:**
npm i @heroui/styles @heroui/react tailwind-variants tailwindcss @tailwindcss/postcss postcss
2. **Create/update `app/globals.css`:**
/* Tailwind CSS v4 - Must be first */ @import "tailwindcss"; /* HeroUI v3 styles - Must be after Tailwind */ @import "@heroui/styles";
3. **Import in `app/layout.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>
);
}4. **Configure PostCSS (`postcss.config.mjs`):**
export default {
plugins: {
"@tailwindcss/postcss": {},
},
};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:
:root {
--🚀 Beautiful, fast and modern React UI library. (Previously NextUI)
Repo: heroui-inc/heroui
Other skills on heroui.
- /heroui-migration
HeroUI v2 to v3 migration guide for agents. Use when migrating HeroUI v2 apps to v3, upgrading components, or accessing migration documentation. Keywords: HeroUI migration, v2 to v3, migration guide, upgrade HeroUI.
Open skill - /heroui-native
HeroUI Native component library for React Native (Tailwind v4 via Uniwind). Use when building mobile UIs with HeroUI Native — creating Buttons, Cards, TextFields, Dialogs; installing heroui-native; configuring dark/light themes; or fetching component docs. Keywords: HeroUI
Open skill