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 のパターンは適用しないでください。プロバイダー、スタイリング、コンポーネント API はすべて変更されています。

機能	v2（使用しないでください）	v3（こちらを使用）
プロバイダー	<HeroUIProvider> が必須	プロバイダーは不要です
アニメーション	framer-motion パッケージ	CSS ベース、追加の依存関係なし
コンポーネント API	フラットな props：<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）を使用します
• 設定よりコンポジション（複合コンポーネント）を優先します
• oklch 色空間を使用した CSS 変数ベースのテーマ設定
• 予測可能なスタイリングのために BEM 命名規則を使用します

---

ドキュメントとコンポーネント情報の参照

コンポーネントの詳細、例、props、実装パターンを確認するには、必ずドキュメントを取得してください。

スクリプトを使用する

# 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 URL を直接指定する

コンポーネントのドキュメント：具体的なケバブケースのスラッグを使って .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

はじめにガイド：https://heroui.com/docs/react/getting-started/quick-start.mdx など、具体的なトピック URL を使用します。

重要： 実装前に、必ずコンポーネントのドキュメントを取得してください。MDX ドキュメントには、完全な例、props、構成、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. onClick ではなく onPress を使用します — アクセシビリティを向上させるため、onPress イベントハンドラーを使用します
4. インポート順序が重要です — Tailwind CSS は必ず HeroUI のスタイルより先にインポートしてください

---

コンポーネントのパターン

すべてのコンポーネントは、上記の複合パターン（Card.Header、Card.Content などのドット記法のサブコンポーネント）を使用します。props に平坦化せず、必ずサブコンポーネントを組み合わせてください。構成と例の詳細については、コンポーネントのドキュメントを取得してください。

---

セマンティックなバリエーション

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