base-ui

Base UI

Base UI を、スタイル未設定でアクセシビリティに配慮した React プリミティブレイヤーとして使用します。ホストアプリのデザインシステムに合わせて各部分を調整しながら、セマンティクス、フォーカス、ラベル、キーボード操作、スタイリングフックを維持してください。

スナップショット：@base-ui/[email protected]（latest、2026-09-04 リリース、2026-10-01 に再確認済み）。プロジェクトで別のバージョンに固定されている場合は、references/source-map.md を参照して更新してください。

ワークフロー

1. コードを変更する前に、プロジェクトでインストールされているパッケージとバージョンを確認します。廃止されたパッケージ名 @base-ui-components/react ではなく、@base-ui/react を使用してください。
2. 実装前に、該当するリファレンスを読みます。
   • references/source-map.md：ドキュメントの参照元、パッケージのステータス、一覧、1.7～1.8 の変更点。
   • references/core-patterns.md：セットアップ、スタイリング、コンポジション、状態、TypeScript、アニメーション、アクセシビリティ、ユーティリティ。
   • references/component-patterns.md：コンポーネントファミリーごとの構造と実装上の注意点。
3. 正確なプロパティ名、イベントの理由、リリース時の挙動、コンポーネント API が重要な場合は、最新の公式ドキュメントを取得します。インストール済みパッケージに含まれるバージョン対応ドキュメント（node_modules/@base-ui/react/docs/index.md）を優先し、次に Context7 ライブラリ /mui/base-ui、または https://base-ui.com/llms.txt にある該当ページの .md URL を使用します。
4. まずドキュメントに記載された複合パーツを使って構築し、その後、プロパティと参照を維持する render プロパティ、または薄いラッパーを通じてのみ、ローカルのデザインシステムコンポーネントでラップします。
5. キーボード操作、フォーカスの復帰、アクセシブルな名前、制御／非制御の状態、ポータルのレイヤー、アニメーションの終了時の挙動、レスポンシブ／モバイルでの挙動を検証します。

実装ルール

• @base-ui/react/dialog、@base-ui/react/combobox、@base-ui/react/field など、コンポーネントのサブパスからインポートします。
• ドキュメントに記載されたパーツを組み合わせます。コンポーネント、パーツ、ショートカットを独自に作らないでください。多くのオーバーレイには、Root、トリガー、ポータル、ポジショナーまたはビューポート、ポップアップ、ラベル／タイトル／説明、閉じるボタン／アクションが必要です。
• Base UI はスタイル未設定として扱います。className、状態に応じて変化する className／style 関数、データ属性、CSS 変数を使用してスタイルを設定します。
• アクセシブルな名前を明示します。Field.Label、コンポーネント固有のラベル、ネイティブラベル、または aria-label／aria-labelledby を使用してください。
• カスタムの render 要素は、参照を転送し、受け取ったすべてのプロパティを基になる DOM ノードに展開して渡す必要があります。
• 製品で外部状態が必要な場合を除き、非制御コンポーネントを優先します。制御する場合は、open／value と onOpenChange／onValueChange を使用します。
• イベントの詳細を意図的に使用します。eventDetails.cancel() は内部の状態更新をブロックし、eventDetails.allowPropagation() は通常なら停止される DOM イベントをバブルさせます。
• Combobox で ID を選択する場合は、Combobox.createItems と Combobox.Root.Props<Value, Multiple, Item> を使用します。Autocomplete には createItems がありません。
• Tailwind v3 のプロジェクトに、Tailwind v4 専用の構文をコピーしないでください。
• アプリにポータルのセットアップがない場合は追加します。アプリのルートを分離し、core patterns のリファレンスにある iOS 26 以降向けの body スタイルを適用してください。

検証チェックリスト

• マークアップに、意図したロール、ラベル、無効／読み取り専用の状態、フォーカス可視時のスタイルが設定されています。
• 関連する箇所で、矢印キー、Home／End、Enter／Space、Escape、タブ順序、フォーカスの復帰を含むキーボード操作が機能します。
• ポップアップ／ドロワー／ダイアログのレイヤーがアプリの上に表示され、トリガー、閉じるボタン、Escape、外部操作、ルート変更／アンマウント時に閉じます。
• フォームコントロールが意図した名前／値を送信し、ネイティブ、サーバー、外部ライブラリの検証エラーを表示します。
• アニメーションで data-starting-style／data-ending-style または keepMounted が適切に使用され、動きを減らす設定やアニメーションなしでも操作できます。
• TypeScript のラッパーが、正しい Component.Part.Props 型（Combobox の 3 つ目の Item ジェネリックを含む）を公開し、参照、ハンドラー、データ属性を失いません。