heroui-native

HeroUI Native 開発ガイド

HeroUI Native は、Uniwind（React Native 向け Tailwind CSS） と React Native を基盤に構築されたコンポーネントライブラリで、モバイルアプリケーション向けにアクセシブルでカスタマイズ可能な UI コンポーネントを提供します。

---

インストール

curl -fsSL https://heroui.com/install | bash -s heroui-native

---

重要：ネイティブ専用 — Web のパターンは使用しないでください

このガイドは HeroUI Native 専用です。 HeroUI React（Web）のパターンは適用しないでください。パッケージ、スタイリングエンジン、色形式はすべて異なります。

機能	React（Web）	Native（モバイル）
スタイリング	Tailwind CSS v4	Uniwind（React Native 向け Tailwind）
色	oklch 形式	HSL 形式
パッケージ	@heroui/react	heroui-native
プラットフォーム	Web ブラウザー	iOS と Android

// CORRECT — Native pattern
import { Button } from "heroui-native";

<Button variant="primary" onPress={() => console.log("Pressed!")}>
	Click me
</Button>;

実装前に、必ず Native のドキュメントを取得してください。

---

基本原則

• 見た目の説明ではなく、セマンティックなバリアント（primary、secondary、tertiary）を使用します
• 設定よりコンポジションを優先します（複合コンポーネント）
• HSL 色形式のテーマ変数を使用します
• Uniwind ユーティリティを使った React Native の StyleSheet パターンを使用します

---

ドキュメントとコンポーネント情報へのアクセス

コンポーネントの詳細、例、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 theme variables
node scripts/get_theme.mjs

# Get non-component docs (guides, releases)
node scripts/get_docs.mjs /docs/native/getting-started/theming

MDX の直接 URL

コンポーネントのドキュメント：具体的なケバブケースのスラッグを使って .mdx を取得します。スラッグが不明な場合は node scripts/list_components.mjs を実行し、プレースホルダーが残った URL は決して取得しないでください。

例：

• Button：https://heroui.com/docs/native/components/button.mdx
• Dialog：https://heroui.com/docs/native/components/dialog.mdx
• TextField：https://heroui.com/docs/native/components/text-field.mdx

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

重要： 実装前に、必ずコンポーネントのドキュメントを取得してください。MDX ドキュメントには、完全な例、props、構成、API リファレンスが含まれています。

---

インストールの基本事項

クイックインストール

npm i heroui-native react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants

フレームワークのセットアップ（Expo — 推奨）

1. 依存関係をインストールします：

npx create-expo-app MyApp
cd MyApp
npm i heroui-native uniwind tailwindcss
npm i react-native-reanimated react-native-gesture-handler react-native-safe-area-context @gorhom/bottom-sheet react-native-svg react-native-worklets tailwind-merge tailwind-variants

2. global.css を作成します：

@import "tailwindcss";
@import "uniwind";
@import "heroui-native/styles";

@source "./node_modules/heroui-native/lib";

3. アプリをプロバイダーでラップします：

import { GestureHandlerRootView } from "react-native-gesture-handler";
import { HeroUINativeProvider } from "heroui-native";
import "./global.css";

export default function Layout() {
	return (
		<GestureHandlerRootView style={{ flex: 1 }}>
			<HeroUINativeProvider>
				<App />
			</HeroUINativeProvider>
		</GestureHandlerRootView>
	);
}

セットアップに関する重要な要件

1. Uniwind が必須です — HeroUI Native は Uniwind（React Native 向け Tailwind CSS）を使用します
2. HeroUINativeProvider が必須です — アプリを HeroUINativeProvider でラップします
3. GestureHandlerRootView が必須です — react-native-gesture-handler の GestureHandlerRootView でラップします
4. 複合コンポーネントを使用します — コンポーネントは複合構造を使用します（例：Card.Header、Card.Body）
5. onClick ではなく onPress を使用します — React Native では onPress イベントハンドラーを使用します
6. プラットフォーム固有のコード — iOS／Android の違いには Platform.OS を使用します

---

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

HeroUI Native は複合コンポーネントのパターンを使用します。各コンポーネントには、ドット記法でアクセスするサブコンポーネントがあります。

例 — Card：

<Card>
	<Card.Header>{/* Icons, badges */}</Card.Header>
	<Card.Body>
		<Card.Title>Title</Card.Title>
		<Card.Description>Description</Card.Description>
	</Card.Body>
	<Card.Footer>{/* Actions */}</Card.Footer>
</Card>

要点：

• 常に複合構造を使用します。props に平坦化しないでください
• サブコンポーネントにはドット記法でアクセスします（例：Card.Header）
• Native の Card では Card.Content ではなく Card.Body を使用します。Title と Description は Body の中に配置します
• 構成と例の全容については、コンポーネントのドキュメントを取得してください

---

セマンティックバリアント

HeroUI では、機能上の意図を伝えるためにセマンティックな命名を使用します。

バリアント	目的	使用方法
primary	次に進むためのメインアクション	コンテキストごとに 1 つ
secondary	代替アクション	複数
tertiary	拒否するアクション（キャンセル、スキップ）	控えめに
danger	破壊的なアクション	必要に応じて
danger-soft	控えめな破壊的アクション	目立たせない
ghost	強調度の低いアクション	最小限の存在感
outline	セカンダリアクション	枠線付きのスタイル

生の色を使用しないでください。セマンティックバリアントはテーマやアクセシビリティに合わせて調整されます。

---

テーマ設定

HeroUI Native では、テーマ設定に Tailwind/Uniwind 経由の CSS 変数を使用します。テーマカラーは global.css で定義します。

@theme {
	--color-accent: hsl(260, 100%, 70%);
	--color-accent-foreground: hsl(0, 0%, 100%);
}

現在のテーマ変数を取得する：

node scripts/get_theme.mjs

テーマカラーにプログラムからアクセスする：

import { useThemeColor } from "heroui-native";

const accentColor = useThemeColor("accent");

テーマの切り替え（ライトモード／ダークモード）：

import { Uniwind, useUniwind } from "uniwind";

const { theme } = useUniwind();
Uniwind.setTheme(theme === "light" ? "dark" : "light");

テーマ設定の詳細については、以下を取得してください：https://heroui.com/docs/native/getting-started/theming.mdx