| name | heroui-react-pro |
| description | HeroUI Pro React component library. Use when building UIs with @heroui-pro/react — charts, forms, navigation, overlays, data display. Teaches compound component patterns, MCP tool usage, v3 conventions, and the CSS styling system. Keywords: HeroUI Pro, @heroui-pro/react, Pro components, Pro MCP. |
| metadata | {"author":"heroui","version":"1.0.0"} |
HeroUI Pro React Development Guide
@heroui-pro/react is a premium component library built on Tailwind CSS v4 and React Aria Components. It extends @heroui/react (the base library) with charts, advanced forms, navigation, overlays, and data display components.
Skills Teach, MCP Does
This skill teaches your agent how to write @heroui-pro/react code correctly. For live data (component docs, CSS files, theme variables), use the HeroUI Pro MCP server (heroui-pro at mcp.heroui.pro).
| Tool | When to use |
|---|
list_components | Discover available @heroui-pro/react components |
get_component_docs | Get compound API, anatomy, props, examples before implementing |
get_css | Understand BEM classes, design tokens, theme variants for customization |
get_docs | Read installation, theming, styling, composition guides |
Always call list_components first to get the up-to-date component list, then get_component_docs before implementing. The component categories listed in this skill are a reference snapshot — new components are added regularly. The MCP list_components tool always returns the current list. If a component name is not in the MCP response, it does not exist yet. Never guess or hallucinate component names.
Two Packages
| Package | What it contains | MCP server |
|---|
@heroui/react | Base components: Button, Card, Modal, TextField, Tabs, Accordion, etc. | heroui-react |
@heroui-pro/react | Pro components: charts, forms, navigation, overlays, data display | heroui-pro |
Import from the correct package:
import {Button, Card, Modal} from "@heroui/react";
import {Sidebar, Command, Sheet, KPI} from "@heroui-pro/react";
Critical v3 Rules
- Tailwind CSS v4 required — v3 is NOT supported
- No Provider needed — components work directly without
<HeroUIProvider>
- Compound components — use dot notation (
Sheet.Trigger, Sheet.Content, Card.Header)
onPress not onClick — for accessibility- Import order matters — Tailwind CSS before HeroUI styles in CSS
@import "tailwindcss";
@import "@heroui/styles";
Component Categories
This list is a snapshot for reference. Always call list_components via the MCP to get the current list — new components and blocks are added regularly.
Charts
AreaChart, BarChart, LineChart, PieChart, RadarChart, RadialChart, ComposedChart, ChartTooltip
Data Display
KPI, KPIGroup, TrendChip, NumberValue, Rating, EmptyState
Forms
CellSelect, CellSwitch, CellSlider, CellColorPicker, InlineSelect, NativeSelect, NumberStepper, CheckboxButtonGroup, RadioButtonGroup
Navigation
Sidebar, FloatingToc, Stepper, Segment
Overlays
Command, ContextMenu, HoverCard, Sheet
Feedback
PressableFeedback, DropZone, EmojiPicker, EmojiReactionButton
Layout
FileTree, Kanban, ItemCard, ItemCardGroup
Key Rules
- Import from
"@heroui/react" for base components, "@heroui-pro/react" for Pro
- Subcomponents via dot notation:
Card.Header, Sheet.Content, Sidebar.Header
- Use
onPress not onClick for Button
Divider does NOT exist — use SeparatorCardHeader/CardContent/CardFooter as direct imports do NOT exist — use Card.Header etc.- Icons:
import { Icon } from "@iconify/react" with the gravity-ui icon set
Semantic Variants
- Button:
variant="primary" (default), "secondary", "tertiary", "outline", "ghost", "danger", "danger-soft"
- Sizes:
size="sm", "md" (default), "lg"
- States:
isDisabled, isPending, isIconOnly, fullWidth
Switch Component (v3 anatomy)
Always use the dot notation anatomy:
import { Switch, Label } from "@heroui/react";
<Switch defaultSelected aria-label="Auto-Lock Doors">
<Switch.Control>
<Switch.Thumb />
</Switch.Control>
</Switch>
<Switch>
<Switch.Control>
<Switch.Thumb />
</Switch.Control>
<Switch.Content>
<Label className="text-sm">Enable notifications</Label>
</Switch.Content>
</Switch>
Design Tokens
- Backgrounds:
bg-background, bg-surface, bg-surface-secondary, bg-overlay
- Text:
text-foreground, text-muted
- Brand:
bg-accent, text-accent-foreground
- Status:
text-success, text-warning, text-danger (each with -foreground)
- Borders:
border-border, border-separator
- Shadows:
shadow-surface, shadow-overlay
- All colors use oklch color space via CSS variables
- No numbered tokens (
default-100, primary-500) — these are v2 and do NOT exist
CSS System
The get_css MCP tool exposes the full shipped CSS from @heroui-pro/react:
- Base variables — design tokens for colors, spacing, radius, shadows
- Component styles — BEM classes with state selectors and modifiers
- Theme variants (e.g. brutalism) — variables, fonts, and component overrides
get_css() → overview of tokens + available styles/themes
get_css({ components: ["sheet", "sidebar"] }) → BEM CSS for those components
get_css({ theme: "brutalism" }) → full theme variant CSS
Components That DONT EXIST — NEVER Use
Divider (use Separator), SelectItem, Progress (use ProgressBar), CardHeader/CardContent/CardFooter as direct imports — use dot notation Card.Header/Card.Content/Card.Footer
Past Corrections (ALWAYS follow these)
- Switch must use dot notation anatomy (
Switch.Control > Switch.Thumb); never the old <Switch>Label</Switch>
- Never apply
shadow-overlay to Card — Card already includes shadow-surface by default
- Wrap Dropdown triggers in a ghost-variant Button (
variant='ghost')
- Use
variant='outline' (not 'outlined') for outlined button styles
- Use
variant='danger-soft' as a single prop for destructive buttons (not color='danger' variant='soft')
- Use HeroUI's built-in components (ColorSwatchPicker, DatePicker, Calendar, CircularProgress) over custom implementations
- Use
ScrollShadow with overflow-y-auto and max-h for scrollable lists
- Apply
rounded-2xl to match HeroUI's default border-radius convention
- Use
no-underline class on breadcrumb links
