panelui

PanelUI

Uniwind を通じて Tailwind CSS でスタイルを設定し、Reanimated で UI スレッド上でアニメーションする、Expo 向けの React Native コンポーネントライブラリです。純粋な TypeScript で、ネイティブモジュールは不要です。Expo Go で動作します。

すべての CLI コマンドは、プロジェクト独自のランナーで実行してください — npx panelui-cli@latest、 pnpm dlx panelui-cli@latest、または bunx panelui-cli@latest を、プロジェクトの packageManager に合わせて使用します。 以下の例では npx を使用しています。

スタイルが適用されていませんか？

ユーザーが、何もスタイルが適用されていない、className が何もしていない、画面が空白、または Uniwind が --color-background を見つけられないと言っている場合は、すぐに setup.md を確認してください。この問題に対するエラーは表示されません。また、ほとんどの場合、metro.config.js のパスが間違っています。コンポーネントのコードを読み始めないでください。

まず、このプロジェクトでの利用方法を確認してください

利用方法は 2 通りあり、どちらも完全にサポートされています。決めつけないでください：

npx panelui-cli@latest mcp   # the MCP server, if the agent supports it

または、MCP を使わずに package.json を読み、panelui.json を探します：

見つかったもの	意味	インポート方法
依存関係に panelui-native がある	パッケージです。デフォルトの利用方法です。	import { Button } from 'panelui-native'
panelui.json がある	ソースがリポジトリにコピーされており、所有・編集できます	import { Button } from '@/components/ui/button'
両方ある	通常の状態です。パッケージのコンポーネントを 1 つフォークしています	ファイルに応じて使い分けます

どちらも見つからない場合は、プロジェクトにまだインストールされていません。新しいアプリでは npx create-panelui-app@latest を、既存のアプリでは setup.md を使用してください。セットアップされていないプロジェクトにコンポーネントのソースを手作業で書き込まないでください。スタイルが適用されず、その原因も分かりにくくなります。

原則

1. 作る前に探してください。 components.md にすべてのコンポーネントが記載されており、100 個以上あります。カスタム UI を書く前に検索してください。「カスタム」のシート、ピッカー、チャート、チャットのトランスクリプトは、ほとんどの場合、すでに用意されています。
2. 記憶ではなく、このスキルでプロパティを確認してください。 各コンポーネントには components/<slug>.md のファイルがあり、構成、型とデフォルト値を含むすべてのプロパティ、バリアント、パーツが記載されています。これらはライブラリの TypeScript から生成されています。これから使うコンポーネントのファイルを読んでください。覚えているプロパティ名はたいてい正しくありません。また、ここでネットワークリクエストを行う必要はありません。
3. パーツを組み合わせてください。 設定画面は Frame + Frame.Panel + Frame.Row です。チャットは MessageScroller + Message です。recipes.md に画面の構成例があります。View よりも複合パーツを優先してください。
4. 色をハードコードしないでください。 すべての色に意味的なトークンを使用します — bg-card、 text-muted-foreground、border-border。色を直接指定すると、6 つのテーマすべてで問題が起きます。

重要なルール

各リンク先のファイルには、誤った例と正しい例のペアが記載されています。

スタイル設定 → rules/styling.md

• 意味的なトークンのみを使用してください。 bg-neutral-900 ではなく bg-card を使います。dark: による上書きは不要です。トークンがすでに対応しており、名前付きテーマ内では dark: は解決されません。
• space-y-* ではなく、常に gap-* を使ってください。 React Native に space-* はありません。
• className はレイアウト用です。 コンポーネントの色や文字種の再設定には使いません。
• 条件付きクラスにはテンプレートリテラルの三項演算子ではなく、cn() を使ってください。
• 動的な色は useCSSVariable で解決してください。 テーマから 16 進数の色を読み取らないでください。
• 新しい任意の値を追加したら、再起動が必要です。 起動中の開発サーバーが開始される前から存在するファイルに h-[330px] を追加しても、何もコンパイルされません。エラーも警告もなく、要素からそのプロパティがひそかに失われます。

構成 → rules/composition.md

• ルートに PanelUIProvider をちょうど1つ配置します。 オーバーレイはそのポータルホストにレンダリングされます。これがないと、Dialog、BottomSheet、Popover、Select、Toast はマウントされても表示されません。
• 複合パーツは対応するルートの内側に配置します。 Card.Header は Card の内側に、Select.Item は Select.Content の内側に配置します。外側で使うと、パーツ名を含むエラーが発生します。
• オーバーレイには open と onOpenChange を渡すか、defaultOpen を使って非制御で動作させます。 閉じるためにオーバーレイを条件付きでレンダリングしないでください。終了アニメーションが完了する必要があります。
• フィールドは Field ＋ Label ＋コントロールで構成します。 コントロールの上に Text を置いた View ではありません。

アニメーション → rules/animation.md

• Reanimated 4 のみを使用します。 React Native のコア Animated は使わないでください。この2つは組み合わせられず、コア Animated を使うと処理が JS スレッドに戻ってしまいます。それこそ、このライブラリが解決する問題です。
• 共有値と useAnimatedStyle を使います。 アニメーションループ内で state を使わないでください。
• tv() はモジュールスコープで呼び出します。 render 内では呼び出さないでください。

ネイティブコントロール → rules/native.md

• 「ネイティブ」とは iOS の Liquid Glass を意味します。 native だけでは不十分です。glass も渡してください。
• ネイティブコントロールは className とすべてのトークンを無視します。 見た目はプラットフォームが管理するため、余白はコンテナ側で設定する必要があります。
• ラベル付きのネイティブボタン内に要素を配置しないでください。 幅が確定せず、JS の try では捕捉できないネイティブコード内でアプリがクラッシュします。

テーマ

3つのファミリー（Panel、Moon、Grass）に、それぞれライトとダークの6つのテーマがあります。各ファミリーはパレットだけでなく、独自の角丸スケールも設定するため、切り替えると UI の形状も変わります。useThemeMode() で実行時に切り替えられます。名前付きテーマは、事前に metro.config.js の extraThemes に記載し、開発サーバーを再起動する必要があります。theming.md を参照してください。

コンポーネントの追加

npx panelui-cli@latest add bottom-sheet     # copies the source in
npx panelui-cli@latest list                 # everything available

プロジェクトでパッケージを使用している場合、インストールは不要です。インポートすればすぐに使えます。コマンドの完全なリファレンスは cli.md、MCP サーバーとそのツールについては mcp.md を参照してください。

コンポーネントの選び方

各コンポーネントの説明とリファレンスへのリンクを含む全リストは、components.md にあります。よくある用途は次のとおりです。

用途	使用するもの
アクション	Button、またはセグメント形式のボタン列や分割ボタンには ButtonGroup
画面下端から表示するパネル	BottomSheet
モーダル	Dialog
起動元に固定するパネル	Popover、またはアクションのリストには Menu
リストから値を選択する	Select、絞り込みが必要な場合は Combobox
何かを検索する	SearchBar。検索結果はフィールドとキーボードの上に表示されます
テキスト入力	Input、Textarea、InputGroup、NumberInput、OtpInput、TagInput
日付または時刻	Calendar、DatePicker、TimePicker、DateTimePicker
フォームの状態とバリデーション	Form ＋ Field
リストの行	Item、アクションを背後に表示する場合は Swipe
設定画面	Frame ＋ Frame.Panel ＋ Frame.Row
指標	Kpi
系列	LineChart、AreaChart、BarChart、PieChart、RingChart、およびその他11種
会話	MessageScroller ＋ Message。ターン間には Marker を配置します
アシスタントの出力	Response、Reasoning、Sources、Task、Plan、CodeBlock
読み込み中	レイアウトには Skeleton、処理中には Spinner または Loader、ストリーミングテキストには Shimmer
表示するものがない	EmptyState
一時的なメッセージ	Toast
フック、ユーティリティ、プリミティブ	hooks.md

詳細リファレンス

• setup.md — インストール方法と、スタイルが適用されないすべての原因
• components.md — すべてのコンポーネントと、それぞれの完全な API を記載したファイル
• recipes.md — 設定、フォーム、チャット、フィルター、リスト、グラフ、検索などの画面全体
• hooks.md — フック、ユーティリティ、テーマ API、プリミティブ
• theming.md — トークン、3 つのファミリー、角丸、useCSSVariable
• cli.md — init、add、list、mcp、panelui.json、レジストリ
• mcp.md — MCP サーバーと 6 つのツール
• rules/styling.md、rules/composition.md、 rules/animation.md、rules/native.md

上記はすべてこのフォルダーにあります。ドキュメントはウェブ上でも Markdown 形式で公開されているため、すべての例を含むページが必要な場合はご利用ください：https://panelui.dev/llms.mdx/<group>/<slug>。https://panelui.dev/llms.txt にインデックスされています。