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 (Mobile)
スタイリング	Tailwind CSS v4	Uniwind (React Native 向け Tailwind)
カラー	oklch フォーマット	HSL フォーマット
パッケージ	@heroui/react	heroui-native
プラットフォーム	Web ブラウザ	iOS & Android

// 正しい — ネイティブパターン
import { Button } from "heroui-native";

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

実装する前に、必ずネイティブドキュメントを取得してください。

---

コア原則

• 視覚的説明よりもセマンティックバリアント (primary, secondary, tertiary)
• 設定よりも構成 (複合コンポーネント)
• HSL カラーフォーマットを持つテーマ変数
• Uniwind ユーティリティを使用した React Native StyleSheet パターン

---

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

コンポーネントの詳細、例、Props、実装パターンについては、必ずドキュメントを取得してください:

スクリプトの使用

# 利用可能なすべてのコンポーネントをリストアップ
node scripts/list_components.mjs

# コンポーネントドキュメント (MDX) を取得
node scripts/get_component_docs.mjs Button
node scripts/get_component_docs.mjs Button Card TextField

# テーマ変数を取得
node scripts/get_theme.mjs

# 非コンポーネントドキュメント (ガイド、リリース) を取得
node scripts/get_docs.mjs /docs/native/getting-started/theming

直接 MDX URLs

コンポーネントドキュメント: https://heroui.com/docs/native/components/{component-name}.mdx

例:

• 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/{topic}.mdx

重要: 実装する前に、必ずコンポーネントドキュメントを取得してください。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. onPress を使用 (onClick ではなく) - 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)
• ネイティブ Card は Card.Body を使用します (Card.Content ではなく); 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