Heroui React
Build accessible React UIs with HeroUI v3, Tailwind CSS v4, and compound components without carrying over obsolete v2 provider patterns.
Overview
HeroUI React is an agent skill for the Build phase that guides HeroUI v3 React UIs with Tailwind v4, compound components, and theme setup—without v2 provider patterns.
Install
npx skills add https://github.com/heroui-inc/heroui --skill heroui-reactWhat is this skill?
- HeroUI v3 only: no HeroUIProvider—compound Card, Modal, and form APIs
- Tailwind CSS v4 plus @heroui/styles with oklch theme variables
- Official install script: curl heroui.com install for @heroui/react
- React Aria Components foundation for accessibility
- Explicit v2 vs v3 migration table (framer-motion vs CSS animations)
- Documented v3 vs v2 comparison table with five feature rows
Adoption & trust: 6.2k installs on skills.sh; 29.6k GitHub stars; 1/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent keeps mixing HeroUI v2 provider and prop APIs with a v3 Tailwind stack, breaking install and component usage.
Who is it for?
Solo builders on React plus Tailwind v4 who want HeroUI components and theme tokens from a single authoritative skill.
Skip if: Projects locked on HeroUI v2, non-React stacks, or teams standardizing on a different component library.
When should I use this skill?
Building UIs with HeroUI, installing @heroui/react, configuring dark/light themes, or fetching HeroUI component docs.
What do I get? / Deliverables
You install @heroui/react correctly, compose v3 compound components, and configure oklch themes so accessible React screens match the current HeroUI docs.
- HeroUI v3 component layouts
- Theme configuration with oklch variables
Recommended Skills
Journey fit
How it compares
Component-library integration skill—not an MCP server or generic CSS-only Tailwind guide.
Common Questions / FAQ
Who is heroui-react for?
Indie React developers adopting HeroUI v3 who need install steps, compound APIs, and theme variables without v2 mistakes.
When should I use heroui-react?
During Build frontend work when creating Buttons, Modals, forms, cards, or fetching HeroUI component docs for a Tailwind v4 React app.
Is heroui-react safe to install?
Check the Security Audits panel on this page; the skill may reference curl-based install—verify URLs and supply-chain policy before running scripts.
SKILL.md
READMESKILL.md - 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 ```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 "t