heroui-react

HeroUI v3 React 开发指南

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

---

安装

curl -fsSL https://heroui.com/install | bash -s heroui-react

---

重要：仅适用于 v3，请忽略 v2 知识

本指南仅适用于 HeroUI v3。 请勿套用 v2 的模式——Provider、样式和组件 API 都已变更：

功能	v2（请勿使用）	v3（请使用）
Provider	必须使用 <HeroUIProvider>	无需 Provider
动画	framer-motion 包	基于 CSS，无需额外依赖
组件 API	扁平属性：<Card title="x">	复合式：<Card><Card.Header>
样式	Tailwind v3 + @heroui/theme	Tailwind v4 + @heroui/styles
包	@heroui/system、@heroui/theme	@heroui/react、@heroui/styles

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

正确（v3 模式）

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

实现前请务必获取 v3 文档。

---

核心原则

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

---

获取文档与组件信息

如需组件详情、示例、属性和实现模式，请务必获取文档：

使用脚本

# 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

直接访问 MDX 地址

组件文档：请使用具体的 kebab-case 别名获取 .mdx。当别名未知时，运行 node scripts/list_components.mjs，并且切勿请求仍包含占位符的 URL。

示例：

• 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

入门指南：请使用具体的主题 URL，例如 https://heroui.com/docs/react/getting-started/quick-start.mdx。

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

---

安装要点

快速安装

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

框架设置（Next.js App Router，推荐）

1. 安装依赖：

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

2. 创建或更新 app/globals.css：

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

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

3. 在 app/layout.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. 配置 PostCSS（postcss.config.mjs）：

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

关键设置要求

1. 必须使用 Tailwind CSS v4 —— HeroUI v3 无法与 Tailwind CSS v3 配合使用
2. 使用复合组件 —— 组件采用复合结构（例如 Card.Header、Card.Content）
3. 使用 onPress，而非 onClick —— 为获得更好的无障碍支持，请使用 onPress 事件处理器
4. 导入顺序很重要 —— 务必先导入 Tailwind CSS，再导入 HeroUI 样式

---

组件模式

所有组件都使用上述复合模式（点号语法的子组件，如 Card.Header、Card.Content）。不要将其扁平化为属性——始终通过子组件进行组合。如需完整的结构组成和示例，请获取组件文档。

---

语义化变体

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

变体	用途	使用场景
primary	推动流程前进的主要操作	每个上下文 1 个
secondary	备选操作	可多个
tertiary	否定性操作（取消、跳过）	少量使用
danger	破坏性操作	必要时使用
ghost	低强调操作	最小权重
outline	次要操作	带边框样式

不要使用原始颜色：语义化变体会适配主题与无障碍需求。

---

主题

HeroUI v3 使用基于 oklch 色彩空间的 CSS 变量：

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

获取当前主题变量：

node scripts/get_theme.mjs

颜色命名：

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

切换主题：

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

如需了解详细的主题配置，请获取：https://heroui.com/docs/react/getting-started/theming.mdx