NarixHine/uni-chem / .agents/skills/heroui-react
heroui-react
FlaggedHeroUI 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.
| File | Kind | Size |
|---|---|---|
| LICENSE.txt | markdown | 11.0 KB |
| SKILL.md | skill md | 6.4 KB |
| scripts/get_component_docs.mjs | script | 4.2 KB |
| scripts/get_docs.mjs | script | 4.2 KB |
| scripts/get_source.mjs | script | 4.4 KB |
| scripts/get_styles.mjs | script | 4.4 KB |
| scripts/get_theme.mjs | script | 5.4 KB |
| scripts/list_components.mjs | script | 3.9 KB |
SKILL.md
View on GitHub---
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)
1. **Install dependencies:**
```bash
npm i @heroui/styles @heroui/react tailwind-variants tailwindcss @tailwindcss/postcss postcss
```
2. **Create/update `app/globals.css`:**
```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`:**
```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`):**
```js
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:
```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`
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |