heroui-react

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

HeroUI v3 React Development Guide

HeroUI v3 React开发指南

HeroUI v3 is a component library built on Tailwind CSS v4 and React Aria Components, providing accessible, customizable UI components for React applications.

HeroUI v3 是基于Tailwind CSS v4和React Aria Components构建的组件库，为React应用提供可访问、可定制的UI组件。

CRITICAL: v3 Only - Ignore v2 Knowledge

重要提示：仅适用于v3 - 忽略v2相关知识

This guide is for HeroUI v3 ONLY. Do NOT use any prior knowledge of HeroUI v2.

本指南仅适用于HeroUI v3。 请勿使用任何HeroUI v2的既有知识。

What Changed in v3

v3的变更内容

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@beta`
Packages	`@heroui/system` , `@heroui/theme`	`@heroui/react@beta` , `@heroui/styles@beta`

特性	v2（请勿使用）	v3（请使用此版本）
提供器	需要 `<HeroUIProvider>`	无需提供器
动画效果	`framer-motion` 包	基于CSS实现，无需额外依赖
组件API	扁平属性： `<Card title="x">`	复合组件： `<Card><Card.Header>`
样式方案	Tailwind v3 + `@heroui/theme`	Tailwind v4 + `@heroui/styles@beta`
包	`@heroui/system` , `@heroui/theme`	`@heroui/react@beta` , `@heroui/styles@beta`

WRONG (v2 patterns)

错误示例（v2写法）

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>;

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)

正确示例（v3写法）

tsx

// DO THIS - v3 pattern (no provider, compound components)
import { Card } from "@heroui/react@beta";

<Card>
	<Card.Header>
		<Card.Title>Product</Card.Title>
		<Card.Description>A great product</Card.Description>
	</Card.Header>
</Card>;

Always fetch v3 docs before implementing. Do not assume v2 patterns work.

tsx

// DO THIS - v3 pattern (no provider, compound components)
import { Card } from "@heroui/react@beta";

<Card>
	<Card.Header>
		<Card.Title>Product</Card.Title>
		<Card.Description>A great product</Card.Description>
	</Card.Header>
</Card>;

实现前请务必查阅v3文档。 不要假设v2的写法在v3中适用。

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

语义化变体（
```
primary
```
、
```
secondary
```
、
```
tertiary
```
）优先于视觉描述
组合优于配置（复合组件）
基于CSS变量的主题系统，使用
```
oklch
```
色彩空间
采用BEM命名规范，确保样式可预测

Accessing Documentation & Component Information

查阅文档与组件信息

For component details, examples, props, and implementation patterns, always fetch documentation:

如需了解组件详情、示例、属性和实现模式，请务必查阅文档：

Using Scripts

使用脚本

bash

undefined

bash

undefined

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

undefined

node scripts/get_docs.mjs /docs/react/getting-started/theming

undefined

Direct MDX URLs

直接MDX链接

Component docs:

https://v3.heroui.com/docs/react/components/{component-name}.mdx

Examples:

Button:

https://v3.heroui.com/docs/react/components/button.mdx

Modal:

https://v3.heroui.com/docs/react/components/modal.mdx

Form:

https://v3.heroui.com/docs/react/components/form.mdx

Getting started guides:

https://v3.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.

组件文档：

https://v3.heroui.com/docs/react/components/{component-name}.mdx

示例：

Button:

https://v3.heroui.com/docs/react/components/button.mdx

Modal:

https://v3.heroui.com/docs/react/components/modal.mdx

Form:

https://v3.heroui.com/docs/react/components/form.mdx

入门指南：

https://v3.heroui.com/docs/react/getting-started/{topic}.mdx

重要提示： 实现前请务必查阅组件文档。MDX文档包含完整的示例、属性、组件结构和API参考。

Installation Essentials

安装要点

CRITICAL: HeroUI v3 is currently in BETA. Always use

@beta

tag when installing packages.

重要提示：HeroUI v3 当前处于BETA阶段。安装包时请务必使用

@beta

标签。

Quick Install

快速安装

bash

npm i @heroui/styles@beta @heroui/react@beta tailwind-variants

bash

npm i @heroui/styles@beta @heroui/react@beta tailwind-variants

Framework Setup (Next.js App Router - Recommended)

框架配置（Next.js App Router - 推荐）

Install dependencies:

bash

npm i @heroui/styles@beta @heroui/react@beta tailwind-variants tailwindcss @tailwindcss/postcss postcss

Create/update
app/globals.css
:

css

/* Tailwind CSS v4 - Must be first */
@import "tailwindcss";

/* HeroUI v3 styles - Must be after Tailwind */
@import "@heroui/styles";

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>
	);
}

Configure PostCSS (
postcss.config.mjs
):

export default {
	plugins: {
		"@tailwindcss/postcss": {},
	},
};

安装依赖：

bash

npm i @heroui/styles@beta @heroui/react@beta tailwind-variants tailwindcss @tailwindcss/postcss postcss

创建/更新
app/globals.css
：

css

/* Tailwind CSS v4 - Must be first */
@import "tailwindcss";

/* HeroUI v3 styles - Must be after Tailwind */
@import "@heroui/styles";

在
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>
	);
}

配置PostCSS（
postcss.config.mjs
）：

export default {
	plugins: {
		"@tailwindcss/postcss": {},
	},
};

Critical Setup Requirements

关键配置要求

Tailwind CSS v4 is MANDATORY - HeroUI v3 will NOT work with Tailwind CSS v3
No Provider Required - Unlike HeroUI v2, v3 components work directly without a Provider
Use Compound Components - Components use compound structure (e.g.,
```
Card.Header
```
,
```
Card.Content
```
)
Use onPress, not onClick - For better accessibility, use
```
onPress
```
event handlers
Import Order Matters - Always import Tailwind CSS before HeroUI styles

必须使用Tailwind CSS v4 - HeroUI v3 无法与Tailwind CSS v3兼容
无需提供器 - 与HeroUI v2不同，v3组件可直接使用，无需提供器
使用复合组件 - 组件采用复合结构（例如
```
Card.Header
```
、
```
Card.Content
```
）
使用onPress而非onClick - 为了更好的可访问性，请使用
```
onPress
```
事件处理函数
导入顺序很重要 - 请务必在HeroUI样式之前导入Tailwind CSS

Component Patterns

组件模式

HeroUI v3 uses compound component patterns. Each component has subcomponents accessed via dot notation.

Example - Card:

tsx

<Card>
	<Card.Header>
		<Card.Title>Title</Card.Title>
		<Card.Description>Description</Card.Description>
	</Card.Header>
	<Card.Content>{/* Content */}</Card.Content>
	<Card.Footer>{/* Actions */}</Card.Footer>
</Card>

Key Points:

Always use compound structure - don't flatten to props
Subcomponents are accessed via dot notation (e.g.,
```
Card.Header
```
)
Each subcomponent may have its own props
Fetch component docs for complete anatomy and examples

HeroUI v3 使用复合组件模式。每个组件都有通过点符号访问的子组件。

示例 - 卡片组件：

tsx

<Card>
	<Card.Header>
		<Card.Title>Title</Card.Title>
		<Card.Description>Description</Card.Description>
	</Card.Header>
	<Card.Content>{/* Content */}</Card.Content>
	<Card.Footer>{/* Actions */}</Card.Footer>
</Card>

关键点：

请始终使用复合结构 - 不要扁平化为属性
子组件通过点符号访问（例如
```
Card.Header
```
）
每个子组件可能有自己的属性
请查阅组件文档获取完整的组件结构和示例

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.

HeroUI 使用语义化命名来传达功能意图：

变体	用途	使用场景
`primary`	推进流程的主要操作	每个场景1个
`secondary`	替代操作	可多个使用
`tertiary`	取消类操作（取消、跳过）	谨慎使用
`danger`	破坏性操作	必要时使用
`ghost`	低强调操作	轻量化样式
`outline`	次要操作	边框样式

请勿使用原始颜色 - 语义化变体可适配主题和可访问性要求。

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://v3.heroui.com/docs/react/getting-started/theming.mdx

HeroUI v3 使用基于

oklch

色彩空间的CSS变量：

css

:root {
	--accent: oklch(0.6204 0.195 253.83);
	--accent-foreground: var(--snow);
	--background: oklch(0.9702 0 0);
	--foreground: var(--eclipse);
}

获取当前主题变量：

bash

node scripts/get_theme.mjs

颜色命名规则：

无后缀 = 背景色（例如
```
--accent
```
）
带
```
-foreground
```
后缀 = 文本颜色（例如
```
--accent-foreground
```
）

主题切换：

html

<html class="dark" data-theme="dark"></html>

如需详细的主题定制指南，请查阅：

https://v3.heroui.com/docs/react/getting-started/theming.mdx