base-ui-react

Base UI React

ステータス：リリース候補版（v1.0.0-rc.0）⚠️ | 最終確認日：2026-08-03

---

Base UI とは？

MUI の、スタイルが設定されておらず、アクセシビリティに配慮した React コンポーネントライブラリです。

• アクセシビリティに配慮した 27 個以上のコンポーネント
• Render props パターン
• スタイルを全面的に制御可能
• Floating UI との統合
• Radix UI の代替

リリース候補版のステータス： v1.0.0-rc.0（安定版 v1.0 GA はまもなくリリース予定ですが、現在も GA 前のため API が変更される可能性があります）

---

クイックスタート

インストール

bun add @base-ui-components/react

基本的なダイアログ

import * as Dialog from '@base-ui-components/react/dialog';

export function MyDialog() {
  return (
    <Dialog.Root>
      <Dialog.Trigger>Open</Dialog.Trigger>
      <Dialog.Portal>
        <Dialog.Backdrop />
        <Dialog.Popup>
          <Dialog.Title>Title</Dialog.Title>
          <Dialog.Description>Content</Dialog.Description>
          <Dialog.Close>Close</Dialog.Close>
        </Dialog.Popup>
      </Dialog.Portal>
    </Dialog.Root>
  );
}

基本的なセレクト

import * as Select from '@base-ui-components/react/select';

<Select.Root>
  <Select.Trigger>
    <Select.Value placeholder="Select" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner>
      <Select.Popup>
        <Select.Option value="1">Option 1</Select.Option>
        <Select.Option value="2">Option 2</Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

完全な例については、references/setup-guide.md を読み込んでください。

---

コアコンポーネント

利用可能（27 個以上）：

• Dialog
• Select
• Popover
• Tooltip
• Accordion
• NumberField
• Checkbox
• Switch
• Tabs
• Slider
• その他...

---

重要なルール

必ず行うこと ✅

1. ポップアップ（Dialog、Select、Popover）には必ず Portal を使います
2. フローティング要素には必ず Positioner を使います
3. モーダルダイアログには必ず Backdrop を追加します
4. Tailwind（または任意の CSS）でスタイルを設定します
5. render props を使います（Radix のように asChild は使いません）
6. アクセシビリティをテストします（ARIA が組み込まれています）
7. Portal のエッジケースに対処します（SSR、ハイドレーション）
8. 破壊的変更についてベータ版のドキュメントを確認します
9. DX を向上させるためにTypeScript を使います
10. 対象ブラウザーでテストします

絶対に行わないこと ❌

1. asChild は絶対に使いません（代わりに render 関数を使います）
2. ポップアップで Portal を省略しません（位置決めが正しく動作しません）
3. Positioner を省略しません（Floating UI が動作しません）
4. API が安定していると思い込まないでください（ベータ版のソフトウェアです）
5. アクセシビリティテストを省略しません
6. React <19 では使いません（React 19 以降が必要です）
7. モーダルで Backdrop を省略しません
8. z-index をハードコードしません（Portal を使います）
9. SSR テストを省略しません（ハイドレーションの問題が発生する可能性があります）
10. Radix との互換性を想定しません（API が異なります）

---

Tailwind との併用

<Dialog.Popup className="rounded-lg bg-white p-6 shadow-xl dark:bg-gray-800">
  <Dialog.Title className="text-xl font-bold text-gray-900 dark:text-white">
    Dialog Title
  </Dialog.Title>
  <Dialog.Description className="mt-2 text-gray-600 dark:text-gray-300">
    Dialog content here
  </Dialog.Description>
  <Dialog.Close className="mt-4 rounded bg-blue-500 px-4 py-2 text-white hover:bg-blue-600">
    Close
  </Dialog.Close>
</Dialog.Popup>

---

よくあるユースケース

ユースケース 1：モーダルダイアログ

<Dialog.Root>
  <Dialog.Trigger className="btn">Open Modal</Dialog.Trigger>
  <Dialog.Portal>
    <Dialog.Backdrop className="fixed inset-0 bg-black/50" />
    <Dialog.Popup className="fixed left-1/2 top-1/2 -translate-x-1/2 -translate-y-1/2 rounded-lg bg-white p-6">
      <Dialog.Title>Confirm Action</Dialog.Title>
      <Dialog.Description>Are you sure?</Dialog.Description>
      <Dialog.Close>Cancel</Dialog.Close>
    </Dialog.Popup>
  </Dialog.Portal>
</Dialog.Root>

ユースケース 2：ドロップダウンセレクト

<Select.Root>
  <Select.Trigger className="flex items-center gap-2 rounded border px-4 py-2">
    <Select.Value placeholder="Select option" />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner className="z-50">
      <Select.Popup className="rounded border bg-white shadow-lg">
        <Select.Option value="1" className="px-4 py-2 hover:bg-gray-100">
          Option 1
        </Select.Option>
        <Select.Option value="2" className="px-4 py-2 hover:bg-gray-100">
          Option 2
        </Select.Option>
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

ユースケース 3：ツールチップ

import * as Tooltip from '@base-ui-components/react/tooltip';

<Tooltip.Root>
  <Tooltip.Trigger>Hover me</Tooltip.Trigger>
  <Tooltip.Portal>
    <Tooltip.Positioner>
      <Tooltip.Popup className="rounded bg-gray-900 px-2 py-1 text-sm text-white">
        Tooltip text
      </Tooltip.Popup>
    </Tooltip.Positioner>
  </Tooltip.Portal>
</Tooltip.Root>

---

ベータ版に関する注意事項

本番環境で安定して使えます：

• Dialog
• Popover
• Tooltip
• Select
• Accordion

注意して使用してください：

• NumberField（API が変更される可能性があります）
• 複雑なフォームコンポーネント

移行方法：

• v1.0 安定版 GA はまもなくリリース予定です（現在は v1.0.0-rc.0）
• 破壊的変更はドキュメントに記載されます
• Codemod が提供される可能性があります

---

Radix UI との比較

特徴	Base UI	Radix UI
パターン	Render props	asChild
位置決め	Floating UI が組み込み済み	手動
ベータ版	はい	安定版
ツリーシェイキング	より優れている	良好
バンドルサイズ	より小さい	より大きい

Base UI を使う場合：

• render props を優先する
• 組み込みの位置決めが必要
• より小さいバンドルを希望する
• ベータ版でも問題ない

Radix を使う場合：

• 安定性が必要
• asChild パターンを優先する
• 確立されたエコシステムが必要

---

リソース

リファレンス（references/）：

• example-reference.md - コンポーネントの詳細な例とパターン
• migration-from-radix.md - Radix UI からの完全な移行ガイド（render prop パターンの説明を含む）
• setup-guide.md - インストールとセットアップの手順

テンプレート（templates/）：

• Accordion.tsx - render props を使った Accordion コンポーネント
• Dialog.tsx - モーダルダイアログの例
• NumberField.tsx - バリデーション付きの数値入力
• Popover.tsx - 位置決め機能付きの Popover
• Select.tsx - ドロップダウンセレクト
• Tooltip.tsx - Tooltip コンポーネント
• migration-example.tsx - Radix から Base UI への移行例

---

公式ドキュメント

• Base UI：https://base-ui.mui.com/
• コンポーネント：https://base-ui.mui.com/components/
• 移行ガイド：https://base-ui.mui.com/base-ui/getting-started/migration/

---

質問や問題がありますか？

1. セットアップについては references/setup-guide.md を確認してください
2. ベータ版のステータスに関する警告を確認してください
3. 最新情報については公式ドキュメントをご覧ください
4. 安定性が必要な場合は Radix もご検討ください