heroui-react-pro

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HeroUI Pro React Development Guide

HeroUI Pro React开发指南

@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.

@heroui-pro/react

是基于 Tailwind CSS v4 和 React Aria Components 构建的高级组件库。它扩展了基础库

@heroui/react

，新增了图表、高级表单、导航、浮层和数据展示类组件。

Skills Teach, MCP Does

技能教学与MCP工具使用

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

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.

本内容指导你的Agent如何正确编写

@heroui-pro/react

代码。如需获取实时数据（组件文档、CSS文件、主题变量），请使用 HeroUI Pro MCP服务器（地址为

mcp.heroui.pro

，标识为

heroui-pro

）。

工具名称	适用场景
`list_components`	查看可用的 `@heroui-pro/react` 组件列表
`get_component_docs`	在实现前获取复合API、组件结构、属性及示例代码
`get_css`	了解用于自定义的BEM类、设计令牌和主题变体
`get_docs`	阅读安装、主题配置、样式设计和组件组合指南

请始终先调用
list_components
获取最新的组件列表，再调用
get_component_docs
后进行组件实现。本内容中列出的组件分类仅为参考快照——新组件会定期添加。MCP的

list_components

工具始终返回当前最新列表。如果组件名称未出现在MCP响应中，则表示该组件暂未存在，切勿猜测或虚构组件名称。

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:

tsx

import {Button, Card, Modal} from "@heroui/react";
import {Sidebar, Command, Sheet, KPI} from "@heroui-pro/react";

包名称	包含内容	MCP服务器标识
`@heroui/react`	基础组件：Button、Card、Modal、TextField、Tabs、Accordion等	`heroui-react`
`@heroui-pro/react`	Pro级组件：图表、表单、导航、浮层、数据展示类组件	`heroui-pro`

请从正确的包中导入组件：

tsx

import {Button, Card, Modal} from "@heroui/react";
import {Sidebar, Command, Sheet, KPI} from "@heroui-pro/react";

Critical v3 Rules

v3版本核心规则

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

css

@import "tailwindcss";
@import "@heroui/styles";

必须使用Tailwind CSS v4 —— 不支持v3版本
无需Provider —— 组件无需
```
<HeroUIProvider>
```
即可直接使用
复合组件 —— 使用点标记法（如
```
Sheet.Trigger
```
、
```
Sheet.Content
```
、
```
Card.Header
```
）
使用
onPress
而非
onClick
—— 为了无障碍访问
导入顺序重要 —— CSS文件中需先导入Tailwind CSS，再导入HeroUI样式

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.

本列表为参考快照。请始终通过MCP调用
list_components
获取最新列表——新组件和模块会定期添加。

Charts

图表类

AreaChart, BarChart, LineChart, PieChart, RadarChart, RadialChart, ComposedChart, ChartTooltip

AreaChart、BarChart、LineChart、PieChart、RadarChart、RadialChart、ComposedChart、ChartTooltip

Data Display

数据展示类

KPI, KPIGroup, TrendChip, NumberValue, Rating, EmptyState

KPI、KPIGroup、TrendChip、NumberValue、Rating、EmptyState

Forms

表单类

CellSelect, CellSwitch, CellSlider, CellColorPicker, InlineSelect, NativeSelect, NumberStepper, CheckboxButtonGroup, RadioButtonGroup

CellSelect、CellSwitch、CellSlider、CellColorPicker、InlineSelect、NativeSelect、NumberStepper、CheckboxButtonGroup、RadioButtonGroup

Navigation

导航类

Sidebar, FloatingToc, Stepper, Segment

Sidebar、FloatingToc、Stepper、Segment

Overlays

浮层类

Command, ContextMenu, HoverCard, Sheet

Command、ContextMenu、HoverCard、Sheet

Feedback

反馈类

PressableFeedback, DropZone, EmojiPicker, EmojiReactionButton

PressableFeedback、DropZone、EmojiPicker、EmojiReactionButton

Layout

布局类

FileTree, Kanban, ItemCard, ItemCardGroup

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
```
Separator
```
```
CardHeader
```
/
```
CardContent
```
/
```
CardFooter
```
as direct imports do NOT exist — use
```
Card.Header
```
etc.
Icons:
```
import { Icon } from "@iconify/react"
```
with the gravity-ui icon set

基础组件从
```
"@heroui/react"
```
导入，Pro级组件从
```
"@heroui-pro/react"
```
导入
子组件通过点标记法调用：
```
Card.Header
```
、
```
Sheet.Content
```
、
```
Sidebar.Header
```
Button组件使用
```
onPress
```
而非
```
onClick
```
不存在
```
Divider
```
组件——请使用
```
Separator
```
不可直接导入
```
CardHeader
```
/
```
CardContent
```
/
```
CardFooter
```
——请使用
```
Card.Header
```
等点标记法形式
图标：通过
```
import { Icon } from "@iconify/react"
```
导入gravity-ui图标集

Semantic Variants

语义化变体

Button:

variant="primary"

(default),

"secondary"

"tertiary"

"outline"

"ghost"

"danger"

"danger-soft"

Sizes:
```
size="sm"
```
,
```
"md"
```
(default),
```
"lg"
```
States:
```
isDisabled
```
,
```
isPending
```
,
```
isIconOnly
```
,
```
fullWidth
```

Button：

variant="primary"

（默认）、

"secondary"

、

"tertiary"

、

"outline"

、

"ghost"

、

"danger"

、

"danger-soft"

尺寸：
```
size="sm"
```
、
```
"md"
```
（默认）、
```
"lg"
```
状态：
```
isDisabled
```
、
```
isPending
```
、
```
isIconOnly
```
、
```
fullWidth
```

Switch Component (v3 anatomy)

Switch组件（v3结构）

Always use the dot notation anatomy:

tsx

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>

请始终使用点标记法结构：

tsx

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

背景色：

bg-background

、

bg-surface

、

bg-surface-secondary

、

bg-overlay

文字色：
```
text-foreground
```
、
```
text-muted
```
品牌色：
```
bg-accent
```
、
```
text-accent-foreground
```

状态色：

text-success

、

text-warning

、

text-danger

（均对应

-foreground

变体）

边框色：
```
border-border
```
、
```
border-separator
```
阴影：
```
shadow-surface
```
、
```
shadow-overlay
```
所有颜色通过CSS变量使用oklch色彩空间
无编号令牌（如
```
default-100
```
、
```
primary-500
```
）——这些属于v2版本，已不再使用

CSS System

CSS系统

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

MCP工具

get_css

可获取

@heroui-pro/react

的完整内置CSS：

基础变量 —— 颜色、间距、圆角、阴影的设计令牌
组件样式 —— 包含状态选择器和修饰符的BEM类
主题变体（如brutalism）—— 变量、字体和组件重写规则

get_css()                                    → 令牌概述 + 可用样式/主题
get_css({ components: ["sheet", "sidebar"] }) → 指定组件的BEM CSS代码
get_css({ theme: "brutalism" })               → 完整主题变体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

Divider（请用Separator）、SelectItem、Progress（请用ProgressBar）、直接导入的CardHeader/CardContent/CardFooter——请使用点标记法

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

Switch组件必须使用点标记法结构（
```
Switch.Control > Switch.Thumb
```
）；切勿使用旧版
```
<Switch>Label</Switch>
```
写法
切勿为Card组件添加
```
shadow-overlay
```
——Card默认已包含
```
shadow-surface
```
请将Dropdown触发器包裹在ghost变体的Button中（
```
variant='ghost'
```
）
按钮轮廓样式使用
```
variant='outline'
```
（而非
```
'outlined'
```
）

破坏性按钮使用

variant='danger-soft'

单一属性（而非

color='danger' variant='soft'

）

使用HeroUI内置组件（ColorSwatchPicker、DatePicker、Calendar、CircularProgress）而非自定义实现
为可滚动列表添加
```
ScrollShadow
```
，并配合
```
overflow-y-auto
```
和
```
max-h
```
使用
应用
```
rounded-2xl
```
以匹配HeroUI默认圆角规范
为面包屑链接添加
```
no-underline
```
类