heroui

HeroUI v3

React（ウェブ）および React Native（モバイル）向けのオープンソース UI コンポーネントライブラリです。Tailwind CSS v4 と React Aria Components を基盤に構築されています。アクセシブルでカスタマイズ可能なウェブコンポーネントを 75 種類以上、ネイティブコンポーネントを 40 種類以上提供します。

技術スタック

プラットフォーム	パッケージ	必要要件
React（ウェブ）	@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（ウェブ）

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>

3 つのインポートパターン

// 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 ウェブコンポーネント（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

コンポーネントの構造、props、使用パターンについては、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 では、3 つのスタイリング方法を利用できます。

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>

検証モードは 2 種類あります。"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