gluestack-ui — React / React Native 向けコピペ UI コンポーネント

位置づけ

v3 gluestack-ui は GeekyAnts が開発する、React・Next.js・React Native 向けの UI コンポーネントとパターン集。従来の npm 依存型 UI ライブラリと異なり、必要な部品だけをプロジェクトへ copy-paste するモデルを採用する（README より）。

スタイルは NativeWind 経由の Tailwind CSS。NativeBase の後継として位置づけられ、v3 では Source-to-Destination モノレポ、RSC 対応、TypeScript-first CLI が追加されている。

~55UI コンポーネント

CLIinit / add / upgrade

RSCNext.js 15 対応

RN WebWeb / モバイル共通

配布モデル: @gluestack-ui/core と @gluestack-ui/utils は npm パッケージとして振る舞い・ユーティリティを提供する。見た目付きの UI 部品は npx gluestack-ui add でアプリ側にコピーされ、プロジェクト内で自由に編集できる。

Source → Destination

編集の正は src/。コンポーネント実装・ドキュメント・サイドバー設定はここに集約され、yarn sync で各アプリへ反映される（ONBOARDING.md）。apps/*/components/ui/ は生成先のため gitignore され、直接編集すると次回 sync で上書きされる。

flowchart LR
  subgraph source["src/（編集する）"]
    UI[src/components/ui/]
    DOCS[src/docs/]
    SB[sidebar.json]
  end
  subgraph packages["packages/（npm 公開）"]
    CORE[gluestack-core]
    UTILS[gluestack-utils]
    CLI[gluestack-ui CLI]
    ADAPT[ui-next-adapter]
  end
  subgraph apps["apps/（生成先）"]
    WEB[website]
    KS[kitchen-sink]
    NEXT[starter-kit-next]
    EXPO[starter-kit-expo]
  end
  UI --> CORE
  UI --> UTILS
  source -->|yarn sync| apps
  CLI -->|init / add| NEXT
  CLI -->|init / add| EXPO

src/components/ui/     # 約55コンポーネント（button, modal, input …）
src/docs/                  # ドキュメント MDX
packages/gluestack-core/ # Creator — スタイルなしの振る舞い層
packages/gluestack-utils/# hooks, aria, NativeWind ヘルパ
packages/gluestack-ui/     # npx gluestack-ui CLI
packages/ui-next-adapter/# Next.js RSC 向け RNW アダプタ
apps/website/              # gluestack.io ドキュメントサイト
apps/kitchen-sink/         # Expo コンポーネントプレイグラウンド
scripts/mappers/         # website / kitchen-sink / starter-kits 同期

パッケージ / アプリ	役割
`@gluestack-ui/core`	Creator ファクトリ。Pressable / View 等のプリミティブに ARIA・状態・Context を載せる（スタイルなし）
`@gluestack-ui/utils`	`tva()`、`useStyleContext`、aria hooks、NativeWind ユーティリティ
`gluestack-ui`（CLI）	`init` / `add` / `upgrade` — プロジェクトへコンポーネントをコピー
`create-gluestack`	`npx create-gluestack` で新規プロジェクトを bootstrap
`ui-next-adapter`	React Native Web コンポーネントを Next.js App Router / RSC で使うためのアダプタ

Creator + Styled

各コンポーネントは 振る舞い と スタイル を分離する。Creator が data-hover 等の data 属性を付与し、Styled 層の NativeWind クラス（data-[hover=true]:bg-primary/90 等）がそれに反応する（ONBOARDING.md）。

createButton({ Root, Text … }) → usePress / useFocus / aria → tva() variants → copy-paste 可能な UI

レイヤ	場所	内容
Creator	`packages/gluestack-core/src/<component>/creator/`	複合コンポーネントの状態管理、アクセシビリティ、Context。スタイルは持たない
Styled	`src/components/ui/<component>/`	RN プリミティブ + Creator 呼び出し + `tva()` で Tailwind クラスを定義
ARIA（任意）	`packages/gluestack-core/src/<component>/aria/`	Web / Native 向けカスタム ARIA hooks

主要ユーティリティ（@gluestack-ui/utils）

tva() — tailwind-variants の薄いラッパ。parentVariants で親 Context の variant に連動
withStyleContext(Component, SCOPE) — 子が読む context prop を受け付けるラッパ
useStyleContext(SCOPE) — 親の variant / size を子コンポーネントが継承（例: ButtonText が Button の size を自動反映）

v3 の特徴

機能	内容
モジュラー構成	必要なコンポーネントだけ add。未使用分のバンドル肥大を避ける
NativeWind	Tailwind クラスで Web / モバイルを同一 API でスタイル
RSC 互換	React Server Components 向けに最適化（Next.js 15）
Universal Design	Web とモバイルで一貫したデザインとコンポーネント API
テーマ	`GluestackUIProvider` と config トークンでライト / ダークを切替
アクセシビリティ	Creator 層で React ARIA 系 hooks を統合。フォーカスリング・キーボード操作を内包

技術スタック（README）: JavaScript、React、React Native、Styled System 系のデザイントークン、Tailwind / NativeWind。

v1 からの移行: gluestack-ui v1 利用者向けに公式ドキュメントのアップグレードガイドと codemod が提供されている（gluestack.io/ui/docs）。

セットアップ

既存の Next.js または Expo プロジェクトが前提。初回は init、以降は必要な部品を add する（packages/gluestack-ui README）。

# 初期セットアップ（Tailwind / Provider / 設定ファイル）
npx gluestack-ui init

# コンポーネントまたは hook を追加
npx gluestack-ui add button
npx gluestack-ui add modal

# 全コンポーネント一括追加
npx gluestack-ui add --all

# バージョンアップ
npx gluestack-ui upgrade

新規プロジェクトは npx create-gluestack でも bootstrap できる。詳細手順は公式ドキュメント（Installation）を参照。

CLI コマンド	用途
`init`	gluestack-ui をプロジェクトに初期設定（Provider、Tailwind、設定 JSON）
`add <name>`	指定コンポーネント / hook をソースからコピー
`add --all`	全コンポーネントを一括追加
`upgrade`	既存コピー済みコンポーネントの更新
`help`	CLI ヘルプ表示

src/components/ui/

リポジトリ内 src/components/ui/ に約 55 ディレクトリがある（ONBOARDING.md は 60 と記載 — all-components 等のメタディレクトリを含む場合）。各ディレクトリは index.tsx、examples/、dependencies.json を持つ。

カテゴリ	例
レイアウト	box, center, hstack, vstack, grid, divider
フォーム	button, input, textarea, checkbox, radio, switch, select, form-control
フィードバック	alert, progress, spinner, skeleton, toast
オーバーレイ	modal, alert-dialog, popover, drawer, actionsheet, bottomsheet, menu, tooltip
表示	avatar, badge, card, heading, text, icon, image
その他	fab, link, pressable, gluestack-ui-provider, portal

各コンポーネントの props・例・依存関係は gluestack.io/ui/docs に掲載。Kitchen Sink（Expo）アプリで実機プレビューも可能。

開発ワークフロー

scripts/dev.ts が src/ を chokidar で監視し、保存時に mapper を呼ぶ。mapper は destination アプリごとにコピー対象をフィルタする。

Mapper	出力先	コピー内容
`website`	`apps/website/`	ドキュメント、examples、sidebar.json
`kitchen-sink`	`apps/kitchen-sink/`	コンポーネントコード + ルート自動生成
`starter-kits`	Next / Expo starter	コンポーネントコードのみ

# ルート package.json の主要スクリプト
yarn dev              # src/ 監視 + 全 mapper
yarn dev:website      # website mapper のみ
yarn sync             # 一括同期（初回セットアップ後）
yarn create:component # 新コンポーネントの scaffold

デモ / テンプレート	用途
gluestack.io	公式ドキュメントサイト（`apps/website`）
Kitchen Sink	Expo 上で全コンポーネントを試すプレイグラウンド
starter-kit-next	Next.js スターター
starter-kit-expo	Expo スターター

一次情報

GitHub: gluestack/gluestack-ui — 本体（MIT）
gluestack.io/ui/docs — コンポーネントリファレンス
gluestack.io/ui/docs — コンポーネントリファレンス・Installation
@gluestack-ui/utils — npm
リポジトリ内 README.md · ONBOARDING.md · CONTRIBUTING.md

gluestack-ui（gluestack/gluestack-ui）

主要ユーティリティ（@gluestack-ui/utils）