HeroUI v3 React 组件库 | 基于 Tailwind CSS v4 的无障碍 UI 框架

heroui-react by heroui-inc/heroui

2,200 周安装量

28,600 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/heroui-inc/heroui --skill heroui-react

开发 JavaScript 框架设计

🇨🇳中文介绍

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 的模式——提供者、样式和组件 API 均已更改：

功能	v2 (请勿使用)	v3 (请使用此版本)
提供者	需要 `<HeroUIProvider>`	无需提供者
动画	`framer-motion` 包	基于 CSS，无需额外依赖
组件 API

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

正确做法 (v3 模式)

// 请这样做 - v3 模式 (无需提供者，复合组件)
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 命名约定以实现可预测的样式

访问文档和组件信息

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

# 列出所有可用组件
node scripts/list_components.mjs

# 获取组件文档 (MDX)
node scripts/get_component_docs.mjs Button
node scripts/get_component_docs.mjs Button Card TextField

# 获取组件源代码
node scripts/get_source.mjs Button

# 获取组件 CSS 样式 (BEM 类)
node scripts/get_styles.mjs Button

# 获取主题变量
node scripts/get_theme.mjs

# 获取非组件文档 (指南、发布说明)
node scripts/get_docs.mjs /docs/react/getting-started/theming

组件文档：https://heroui.com/docs/react/components/{component-name}.mdx

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

入门指南：https://heroui.com/docs/react/getting-started/{topic}.mdx

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

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

框架设置 (Next.js App Router - 推荐)

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

创建/更新 app/globals.css：

/* Tailwind CSS v4 - 必须放在首位 */

@import "tailwindcss";

/* HeroUI v3 样式 - 必须在 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>
				{/* HeroUI v3 无需提供者！ */}
				{children}
			</body>
		</html>
	);
}

4. 配置 PostCSS (postcss.config.mjs)：

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

Tailwind CSS v4 是必需的 - HeroUI v3 无法与 Tailwind CSS v3 一起工作
使用复合组件 - 组件采用复合结构 (例如，Card.Header, Card.Content)
使用 onPress，而非 onClick - 为了更好的无障碍性，请使用 onPress 事件处理器
导入顺序很重要 - 始终先导入 Tailwind CSS，再导入 HeroUI 样式

所有组件都使用上述的复合模式（点符号子组件，如 Card.Header, Card.Content）。不要扁平化为属性——始终使用子组件进行组合。请获取组件文档以了解完整的结构剖析和示例。

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

变体	目的	用法
`primary`	向前推进的主要操作	每个上下文 1 个
`secondary`	替代操作	多个
`tertiary`	取消性操作 (取消、跳过)	谨慎使用
`danger`	破坏性操作	需要时使用
`ghost`	低强调度操作	最小权重
`outline`	次要操作	边框样式

不要使用原始颜色 - 语义化变体会根据主题和无障碍性进行适配。

HeroUI v3 使用 CSS 变量和 oklch 色彩空间：

: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

2026 年 1 月 27 日

🇺🇸English

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

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`

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

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

# 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

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

Framework Setup (Next.js App Router - Recommended)

Install dependencies:

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

Create/updateapp/globals.css:

/* Tailwind CSS v4 - Must be first */

@import "tailwindcss";

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

3. Import inapp/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. Configure 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
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

Component Patterns

All components use the compound pattern shown above (dot-notation subcomponents like Card.Header, Card.Content). Don't flatten to props — always compose with subcomponents. Fetch component docs for complete anatomy and examples.

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

Don't use raw colors - semantic variants adapt to themes and accessibility.

Theming

HeroUI v3 uses CSS variables with oklch color space:

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

node scripts/get_theme.mjs

Color naming:

Without suffix = background (e.g., --accent)
With -foreground = text color (e.g., --accent-foreground)

Theme switching:

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

For detailed theming, fetch: https://heroui.com/docs/react/getting-started/theming.mdx

Weekly Installs

2.2K

Repository

heroui-inc/heroui

GitHub Stars

28.6K

First Seen

Jan 27, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex1.9K

opencode1.9K

github-copilot1.9K

gemini-cli1.9K

cursor1.8K

amp1.8K

React 组合模式指南：Vercel 组件架构最佳实践，提升代码可维护性

102,200 周安装

HeroUI v3 React 组件库 | 基于 Tailwind CSS v4 的无障碍 UI 框架

🇨🇳中文介绍

HeroUI v3 React 开发指南

安装

重要提示：仅限 v3 - 忽略 v2 知识

相关 Skills

正确做法 (v3 模式)

核心原则

访问文档和组件信息

使用脚本

直接 MDX 链接

安装要点

快速安装