heroui

HeroUI v3

一个适用于 React（Web）和 React Native（移动端）的开源 UI 组件库。基于 Tailwind CSS v4 和 React Aria Components 构建，提供 75+ 个无障碍且可自定义的 Web 组件，以及 40+ 个原生组件。

技术栈

平台	包	要求
React（Web）	@heroui/react、@heroui/styles	React 19+、Tailwind CSS v4
React Native	heroui-native	React Native、Uniwind、react-native-reanimated 4.1+、react-native-gesture-handler 2.28+

快速设置

React（Web）

npm i @heroui/react @heroui/styles

/* globals.css — order matters */
@import "tailwindcss";
@import "@heroui/styles";

import { Button } from "@heroui/react";

function App() {
  return <Button>Click me</Button>;
}

React Native

npm install heroui-native react-native-reanimated@^4.1.1 react-native-gesture-handler@^2.28.0 react-native-worklets@^0.5.1 react-native-safe-area-context@^5.6.0 react-native-svg@^15.12.1 tailwind-variants@^3.2.2 tailwind-merge@^3.4.0

/* global.css */
@import "tailwindcss";
@import "uniwind";
@import "heroui-native/styles";
@source "./node_modules/heroui-native/lib";

import { HeroUINativeProvider } from "heroui-native";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { Button } from "heroui-native";

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <HeroUINativeProvider>
        <Button onPress={() => console.log("Pressed!")}>Get Started</Button>
      </HeroUINativeProvider>
    </GestureHandlerRootView>
  );
}

详细的设置说明请参阅 react-setup.md 和 native-setup.md。

组件架构

HeroUI v3 使用复合组件组合，并采用点号表示法：

<Modal>
  <Button>Open</Button>
  <Modal.Backdrop>
    <Modal.Container>
      <Modal.Dialog>
        <Modal.Header>
          <Modal.Heading>Title</Modal.Heading>
        </Modal.Header>
        <Modal.Body>Content</Modal.Body>
        <Modal.Footer>
          <Button slot="close">Close</Button>
        </Modal.Footer>
      </Modal.Dialog>
    </Modal.Container>
  </Modal.Backdrop>
</Modal>

三种导入模式

// 1. Compound (recommended)
<Alert>
  <Alert.Icon />
  <Alert.Content>
    <Alert.Title>Success</Alert.Title>
  </Alert.Content>
</Alert>

// 2. With .Root suffix
<Alert.Root>
  <Alert.Icon />
</Alert.Root>

// 3. Named exports
import { AlertRoot, AlertIcon, AlertContent, AlertTitle } from "@heroui/react";

类型导入

import type { ButtonRootProps, AvatarRootProps } from "@heroui/react";

React Web 组件（75+）

类别	组件
按钮	Button、ButtonGroup、CloseButton、ToggleButton、ToggleButtonGroup
集合	Dropdown、ListBox、TagGroup
颜色	ColorArea、ColorField、ColorPicker、ColorSlider、ColorSwatch、ColorSwatchPicker
控件	Slider、Switch
数据展示	Badge、Chip、Table
日期和时间	Calendar、DateField、DatePicker、DateRangePicker、RangeCalendar、TimeField
反馈	Alert、Meter、ProgressBar、ProgressCircle、Skeleton、Spinner、Toast
表单	Checkbox、CheckboxGroup、Description、ErrorMessage、FieldError、Fieldset、Form、Input、InputGroup、InputOTP、Label、NumberField、RadioGroup、SearchField、TextField、TextArea
布局	Card、Separator、Surface、Toolbar
媒体	Avatar
导航	Accordion、Breadcrumbs、Disclosure、DisclosureGroup、Link、Pagination、Tabs
覆盖层	AlertDialog、Drawer、Modal、Popover、Tooltip
选择器	Autocomplete、ComboBox、Select
排版	Kbd
工具	ScrollShadow

有关组件结构、属性和用法模式，请参阅 react-components.md。

React Native 组件（40+）

类别	组件
按钮	Button、CloseButton、LinkButton
集合	Menu、TagGroup
控件	Slider、Switch、Checkbox
数据展示	Chip、Avatar
反馈	Alert、Spinner、Skeleton、SkeletonGroup、Toast
表单	ControlField、Description、FieldError、Input、InputGroup、InputOTP、Label、RadioGroup、SearchField、Select、TextArea、TextField
布局	Card、Separator、Surface、Accordion、ListGroup、Tabs
覆盖层	BottomSheet、Dialog、Popover
工具	PressableFeedback、ScrollShadow

有关原生组件的详细信息，请参阅 native-components.md。

样式系统

HeroUI v3 提供三种样式设置方式：

1. BEM 类

<button className="button button--primary button--lg">Click</button>

类名模式：.{block}、.{block}__{element}、.{block}--{modifier}

2. 变体函数（类型安全）

import { buttonVariants } from "@heroui/styles";

<a className={buttonVariants({ variant: "primary", size: "lg" })} href="/about">
  About
</a>

变体函数与框架无关，可用于 Vue、Svelte 和原生 HTML。

3. Tailwind CSS 类 + className 属性

<Button className="rounded-full shadow-lg">Styled</Button>

自定义变体

import { buttonVariants, tv } from "@heroui/styles";

const myButton = tv({
  extend: buttonVariants,
  base: "font-semibold shadow-md",
  variants: {
    radius: { lg: "rounded-lg", md: "rounded-md" },
  },
});

用于自定义元素的 render 属性

<Button
  render={(domProps, { isPressed }) => (
    <motion.button {...domProps} animate={{ scale: isPressed ? 0.9 : 1 }} />
  )}
>
  Animated
</Button>

有关主题设置、CSS 变量、深色模式、自定义主题和组件级覆盖，请参阅 theming-and-styling.md。

常见属性模式

交互状态（数据属性）

状态	属性	CSS 伪类
悬停	[data-hovered="true"]	:hover
按下	[data-pressed="true"]	:active
焦点	[data-focus-visible="true"]	:focus-visible
禁用	[aria-disabled="true"]	:disabled
已选中	[data-selected="true"]	—
打开	[data-open="true"]	—
进入中	[data-entering]	—
退出中	[data-exiting]	—

事件处理器

HeroUI 使用 React Aria 的按压事件，而不是原生点击事件：

<Button onPress={(e) => console.log("pressed")} />

覆盖层状态管理

import { useOverlayState } from "@heroui/react";

const state = useOverlayState({ defaultOpen: false });
// state.isOpen, state.open(), state.close(), state.toggle(), state.setOpen()

表单验证

import { Form, TextField, Button } from "@heroui/react";

<Form validationBehavior="aria" onSubmit={handleSubmit}>
  <TextField name="email" isRequired>
    <Label>Email</Label>
    <Input />
    <FieldError />
  </TextField>
  <Button type="submit">Submit</Button>
</Form>

两种验证模式："native"（阻止提交）和 "aria"（实时显示错误）。

文档资源

资源	URL
React 文档	https://www.heroui.com/docs/react/getting-started
Native 文档	https://www.heroui.com/docs/native/getting-started
所有 React 组件	https://www.heroui.com/docs/react/components
所有 Native 组件	https://www.heroui.com/docs/native/components
主题构建器	https://www.heroui.com/themes
迁移（v2 到 v3）	https://www.heroui.com/docs/react/migration