构建界面，
快人一步
HeroUI 将 React Aria 的可访问性严谨与 Tailwind CSS v4 的实用优先理念融为一体。复合组件 API，零样板代码，开箱即用。
import { Button, Card } from "@heroui/react";
export default function App() {
return (
<Card className="p-6">
<Card.Header>
<h2>欢迎使用 HeroUI</h2>
</Card.Header>
<Card.Content>
<p>零 Provider，零样板代码。</p>
</Card.Content>
<Card.Footer>
<Button color="primary">
开始构建
</Button>
</Card.Footer>
</Card>
);
}// 为什么选择 HeroUI
为生产环境而生的
设计工程哲学
每一个设计决策都围绕开发者体验与终端用户可访问性展开。
默认可访问
基于 React Aria 构建，符合 WCAG 的键盘、焦点与屏幕阅读器行为，无需额外配置。
Tailwind CSS v4
现代引擎驱动，无 CSS-in-JS 运行时开销，输出更小、构建更快。
复合组件
可组合的 API（Card.Header、Card.Content），取代层层嵌套的 props 传递。
零样板代码
无需 Provider 包裹层。与 Chakra、MUI 不同，引入即用，无全局配置。
AI 原生
提供 MCP 服务器、llms.txt 以及 Agent 技能，让 AI 助手深度理解你的组件。
久经考验
前身为 NextUI，已获数千个生产环境应用信赖，稳定可靠。
// 设计原则
活的图书馆，
而非静态快照
HeroUI v3 反对复制粘贴式的组件方案。它是一个持续生长的花园 — 自动更新、持续演进、与 React、Tailwind 和浏览器标准保持同步。
“我们选择 React Aria 是因为它提供了大规模无障碍的原语。自 v2 起采用，保留了 isDisabled、onPress 等开发者习惯的接口。”
— 致谢 Devon Govett 与 Adobe React Spectrum 团队
默认即美观
每个组件出厂即具备专业级外观，无需从零调样式。
无障碍内建
基于 React Aria，键盘导航、焦点管理、屏幕阅读器支持开箱即用，符合 WCAG 标准。
灵活可组合
复合组件 API 让每个部件都可独立替换、重组，而非锁死在 props 里。
开发者友好
完整 TypeScript 类型提示，IDE 自动补全，减少查阅文档的次数。
轻量无负担
Tree-shakeable 架构，只打包你实际用到的组件代码。
面向未来
原生支持 React 19、Tailwind v4、RSC，以及 AI 辅助开发工具链。
// 组件全景
60+ 组件，覆盖全场景
从按钮到日期选择器，从表单到弹层 — 9 大分类，每个组件都经过无障碍与性能的双重打磨。更多组件持续加入中。
按钮
选择与列表
颜色与范围
数据展示
日期与时间
反馈与状态
表单
导航与结构
弹层与对话
// 组件实战
简洁的 API，
强大的能力
复合组件设计让每个部件都可独立组合。以下是最常用的几个组件。
import { Button } from "@heroui/react";
// 6 种语义变体
<Button variant="primary">主要</Button>
<Button variant="secondary">次要</Button>
<Button variant="tertiary">三级</Button>
<Button variant="outline">描边</Button>
<Button variant="ghost">幽灵</Button>
<Button variant="danger">危险</Button>
// 尺寸与状态
<Button size="sm">小</Button>
<Button size="lg" fullWidth>全宽大按钮</Button>
<Button isPending>加载中...</Button>
<Button isIconOnly><Icon /></Button>// 包含的包
按需取用，
轻重自如
从完整合集到单组件独立包，HeroUI 的模块化架构让你只为用到的代码买单。
@heroui/react完整组件合集 — 一次安装，全部拥有
@heroui/styles仅包含样式 / 主题，适合自定义组件体系
@heroui/button 等独立包按需引入，支持 tree-shake 极致精简
// 快速开始
两行代码，即刻启程
无需 Provider，无需配置文件。安装、引入、渲染。
@import "tailwindcss";
@import "@heroui/styles";
// 引入顺序很重要：先 Tailwind，后 HeroUI
import { Button } from "@heroui/react";
export default () => <Button>Hello HeroUI</Button>;
// 主题与颜色
语义化颜色，
而非大色板
HeroUI v3 的颜色系统围绕语义意图构建。少量角色表达目的与状态， 多数颜色由基础值通过 color-mix 自动派生，维持对比度与主题一致性。
--accent强调色 / 主操作--success成功状态--warning警告状态--danger危险 / 错误--foreground主文本色--background页面背景--surface卡片 / 面板--border边框 / 分隔支持 Theme Builder 可视化调整颜色、圆角、字体并导出 CSS。
/* 覆盖主题颜色 */
:root {
--accent: oklch(65% 0.2 25);
--accent-foreground: oklch(98% 0 0);
--radius: 0.75rem;
}
/* 深色模式 */
.dark {
--accent: oklch(70% 0.18 25);
--background: oklch(12% 0.005 286);
}
/* 新增语义色 */
:root {
--info: oklch(65% 0.15 240);
--info-foreground: white;
}
@theme inline {
--color-info: var(--info);
--color-info-foreground: var(--info-foreground);
}
/* 现在可以用 bg-info、text-info-foreground */布局与交互变量
// 样式定制
四种方式，深度定制
从轻量覆盖到完全重构，HeroUI 提供渐进式的定制路径。 每个槽位都可独立修改，没有锁死的黑盒。
Tailwind 工具类
直接传入 className，与 Tailwind 生态无缝衔接
<Card className="border-2 border-blue-500">
<Card.Title className="text-blue-900">
自定义标题
</Card.Title>
</Card>BEM CSS 类覆盖
每个组件按 BEM 命名暴露样式钩子，精准覆盖不破坏结构
@layer components {
.card--secondary {
/* 覆盖次级卡片 */
}
.card__title {
@apply text-lg font-bold;
}
.button--primary {
@apply rounded-full;
}
}tailwind-variants 扩展
用 tv() 扩展组件变体，新增 radius、size 等维度
import { tv } from "tailwind-variants";
import { buttonVariants } from "@heroui/react";
const myButton = tv({
extend: buttonVariants,
variants: {
radius: {
pill: "rounded-full",
sharp: "rounded-none",
},
},
});CSS 变量主题
覆盖语义变量即可全局换肤，支持亮/暗模式独立配置
:root {
--accent: oklch(65% 0.2 150);
--radius: 1rem;
}
.dark {
--accent: oklch(70% 0.18 150);
--background: oklch(10% 0.01 280);
}// 适用于谁
你的下一个项目，
值得更好的起点
SaaS 应用
开箱即用的表单、表格、浮层与通知，快速搭建完整工作流。
仪表盘与管理后台
借助统一的设计令牌，构建数据密集的布局，保持视觉一致性。
电商前端
高性能、可访问、对 SEO 友好的组件，转化不留死角。
营销站点与落地页
精致界面，却不带沉重的运行时开销。首屏即巅峰。
以及任何重视设计质量与可访问性的 React / Next.js 项目
// 生态系统
不止于 Web 组件库
从 Web 到移动端，从代码到自然语言 — HeroUI 正在构建完整的 UI 生态。
HeroUI v3
稳定版React Web
面向 Web 的完整组件库，基于 Tailwind CSS v4 与 React Aria Components，支持 React 19+ 与 TypeScript。
HeroUI Native
v1.0+React Native
为移动端提供美观且可访问的组件，包含 BottomSheet、PressableFeedback 等原生交互模式。
HeroUI Chat
新平台自然语言
用自然语言描述界面需求，AI 直接生成可运行的 HeroUI 组件代码。
UI for LLMs
即将推出MCP 协议
面向大语言模型的 UI 渲染层，让 AI 输出不再只是文本 — 即将推出。
// AI 赋能的开发
让 AI 助手
真正理解你的组件
HeroUI 专为 AI 辅助的开发工作流而打造。从 MCP 协议到 llms.txt，你的 AI 编辑器将获得完整的组件上下文。
MCP 服务器
@heroui/react-mcp能理解你主题的组件 — 可在 Cursor、Claude Code、Windsurf 或任何兼容 MCP 的编辑器中安装。
llms.txt
heroui.com/llms.txt面向 LLM 的结构化上下文，覆盖每个组件的 API、用法与约束。
Agent 技能
npx heroui-cli agents-md一条命令为 Cursor、Claude Code 等安装组件感知技能。
// 版本演进
持续演进，从未停歇
从 v3.0.0 到 v3.2.x，每个版本都在扩展边界。
// 对比其他方案
不是又一个组件库
与主流方案的核心差异，一目了然。
// 常见问题
你想知道的，
都在这里
更多问题欢迎在 GitHub Discussions 或 Discord 中提出。
HeroUI 是免费的吗？
是的，HeroUI 完全免费开源，采用 Apache License 2.0 许可证，可自由用于商业与个人项目。
可以用于生产环境吗？
当然可以。HeroUI 前身为 NextUI，已获数千个生产环境应用信赖，v3 在此基础上进一步提升了稳定性与性能。
如何自定义组件样式？
支持多种方式：Tailwind 工具类直接覆盖、样式变量调整、BEM 修饰符、或重组复合组件的部件。每个槽位都可独立定制。
支持 TypeScript 吗？
完整支持。所有组件均提供精确的类型定义，IDE 自动补全开箱即用。
无障碍水平如何？
基于 React Aria 构建，符合 WCAG 标准，包含键盘导航、焦点管理与屏幕阅读器支持，无需额外配置。
样式能脱离 React 使用吗？
可以。@heroui/styles 包可独立用于普通网页，配合 Tailwind 即可，不强制绑定 React。
有 Figma 设计套件吗？
有。HeroUI Figma Kit V3 已在 Figma Community 发布，设计与代码保持同步。
// 社区
与我们同行
无论是功能请求、Bug 报告，还是想要展示的项目，都欢迎你的参与。