base-ui

Base UI（React）

Base UI は、スタイルの設定されていない、組み合わせ可能な React コンポーネントを提供します。このスキルでは、複数パーツで構成されるコンポーネントの組み立て、render prop を使った合成、スタイルを設定する際のアクセシビリティ要件への対応に重点を置いています。

クイックナビゲーション（リファレンス）

ユーティリティ

• references/csp-provider.md
• references/direction-provider.md
• references/merge-props.md
• references/use-render.md

フォームと入力

• references/form.md
• references/fieldset.md
• references/input.md
• references/number-field.md
• references/otp-field.md
• references/radio.md
• references/select.md
• references/slider.md
• references/switch.md

フィードバックとステータス

• references/meter.md
• references/progress.md
• references/toast.md

メニュー、ナビゲーション、オーバーレイ

• references/drawer.md
• references/menu.md
• references/menubar.md
• references/navigation-menu.md
• references/popover.md
• references/preview-card.md
• references/tooltip.md

トグルとコントロール

• references/toggle.md
• references/toggle-group.md
• references/toolbar.md

レイアウトと区切り

• references/scroll-area.md
• references/separator.md

v1.7.0 - v1.8.0 の主な変更点

• Combobox に、オプションコレクションをプログラムで構築するための createItems コレクション API が追加されました。
• Avatar.Image に keepMounted prop が追加され、画像サブツリーをマウントしたままにできるようになりました（再マウント時のちらつき防止に役立ちます）。
• Toast で現在のトーストから導出する関数による更新が可能になり、Toast.Title、Toast.Description、Toast.Action でも render prop が有効になりました。
• Autocomplete と Combobox が input-press および cancel-open の変更イベント詳細を発行するようになり、インライン Combobox では expanded 状態が公開されます。
• Combobox.Item と Select.Item は、ルートから無効状態を継承するようになりました。
• Form はドキュメント上の順序で最初の無効なフィールドにフォーカスし、Field は非同期バリデーション中に中立的な有効性を公開します。
• ドロワー、メニュー、ツールチップ、スクロール領域全体で、主にアクセシビリティ、ポップアップ／オーバーレイの動作、バンドルサイズが改善されました。

v1.4.1 の主な変更点

• mergeProps が複数引数を取るイベントハンドラーを正しく転送するようになりました。これは、イベントとともに追加の詳細情報や状態を受け取るラップ済みコールバックで重要です。
• display: contents を使ったタブ移動可能性が修正されました。DOM 構造をフラット化するカスタムラッパーや render prop の合成を再テストしてください。
• トリガーをすばやくホバーした際のポップアップサイズが修正され、スクロールコンテナー内でクリップされた項目のハイライト解除がより確実になりました。

v1.6.0 の主な変更点

• OTPFieldPreview 名前空間が OTPField に改名されました。プレビュー名前空間を参照していたインポートを更新してください。
• Accordion、Alert Dialog、Autocomplete、Avatar、Checkbox、Dialog、Drawer、Field、Menu、Number Field、OTP Field など、幅広いコンポーネントの動作上のバグが修正されました。

v1.5.0 の主な変更点

• OTPField では sanitizeValue() が normalizeValue() に置き換えられ、キーボードショートカットとバリデーション合成の動作が改善されました。
• ポップアップベースのコンポーネントが、制御された open 状態をより一貫して尊重するようになりました。これは Popover、Menu、PreviewCard および関連するオーバーレイに影響します。
• Form、Field、OTPField では、以前の flushSync スタイルのバリデーションタイミングパターンを使用しなくなりました。ローカルのバリデーションスケジュールに関する回避策を残す前に、再テストしてください。
• NavigationMenu、Popover、ScrollArea 全体で RTL の動作が修正されました。
• Drawer.Viewport が style を転送するようになりました。カスタムのビューポートサイズ設定やアニメーション付きレイアウトの制約に役立ちます。

v1.4.0 の主な変更点

• ワンタイムパスワードや確認コードの入力に使えるプレビュー用プリミティブとして、OTPField が追加されました。
• 非表示の入力で form と suppressHydrationWarning が公開されるようになりました。外部フォームにコントロールを送信する場合や、SSR 境界をまたいでハイドレーションする場合に重要です。
• 合成されたコンポーネントで、render の警告と preventBaseUIHandler() の実行時の動作がより安定しました。
• Drawer、NavigationMenu、Select、Slider、Toast、Switch のオーバーレイ／入力プリミティブに重要な動作修正が行われました。

v1.3.0 の主な変更点

• Drawer が安定版になりました（プレビューではなくなりました）。主要なオーバーレイプリミティブとして扱ってください。
• Autocomplete と Combobox に InputGroup が追加されました。Combobox、Select、Slider には Label パーツが追加されました。
• Drawer に、明示的なスワイプ操作を可能にする SwipeArea が追加されました。
• Tooltip に closeOnClick が追加されました。Toast ではすべてのトーストを閉じられます。
• Checkbox、Radio Group、Switch で、aria-labelledby の自動サポートが改善されました。
• v1.2.0 で追加された render プロパティのサポートは引き続き利用できます。遅延要素も対象です。

適用する基本概念

• スタイルなしプリミティブ：すべてのビジュアルは CSS／Tailwind／CSS Modules で設定します。Base UI は動作とアクセシビリティを担います。
• 複数パーツの構成：ほとんどのコンポーネントは Root とサブパーツ（Trigger、Popup、Item など）で構成されます。これらを明示的に組み合わせてください。
• render プロパティ：デフォルト要素を置き換えたり、独自のコンポーネントでラップしたりできます。関数形式を使う場合は、mergeProps でプロパティを手動でマージしてください。
• 状態に応じたスタイリング：多くのパーツでは、data-[popup-open]、data-[highlighted]、data-[pressed]、data-[checked]、data-[invalid] などのデータ属性が公開されています。
• オーバーレイにはポータルを使用：ポップオーバー、メニュー、ツールチップ、セレクト、ナビゲーションメニューのコンテンツ、プレビューカードには、Portal + Positioner + Popup を使用してください。

レシピ

1）アクセシブルなフォームをすばやく作成する

• Form で入力をラップし、送信とエラーの集約を行います。
• name を指定した Field.Root を使用し、ラベルとエラーには Field.Label、Field.Control、Field.Error を使います。
• 関連するフィールドを Fieldset.Root + Fieldset.Legend でグループ化します。
• Radio グループには、aria-labelledby を指定して RadioGroup を使うか、Fieldset.Root 経由で RadioGroup をレンダリングし、各選択肢に Field.Label を使います。
• すべてのフォームコントロールに、アクセシブルな名前（ラベル、または Field／Fieldset のラベル付けパターン）を設定してください。

2）render + mergeProps で組み合わせる

• render に React 要素を渡すと、Base UI がプロパティを自動でマージします。
• render に関数を渡す場合は、Base UI のプロパティと独自のプロパティを mergeProps でマージしてください。
• 必要に応じて Base UI の内部動作を止めるには、マージしたイベントハンドラー内で event.preventBaseUIHandler() を使います（合成イベントのみ）。

3）オーバーレイとメニュー（ポータル化された UI）

• Root + Trigger + Portal + Positioner + Popup を使ってポップアップを構築します。
• メニューやナビゲーションには、必要に応じて Item、Separator、Arrow、リスト／ビューポートのパーツを追加します。
• NavigationMenu.Link は、フレームワークのルーターリンク向けに render をサポートしています。

4）トースト

• アプリ全体（またはサブツリー）を Toast.Provider でラップします。
• Toast.useToastManager() を使ってトーストを作成します。
• Toast.Portal 内に Toast.Viewport をレンダリングし、toasts を Toast.Root の項目にマッピングして、Toast.Content、Toast.Title、Toast.Description、Toast.Close を配置します。

5）RTL と CSP の制約

• RTL の動作には DirectionProvider でラップし、dir="rtl" も設定します（プロバイダーは DOM の方向を設定しません）。
• 厳格な CSP では、CSPProvider でラップして nonce を渡すか、アプリ側で外部スタイルを用意する場合はインラインの style 要素を無効にします。インラインの style 属性は CSPProvider で制御されないため注意してください。

6）スライダーと範囲

• 単一値のスライダー：Slider.Thumb を 1 つ使います。
• 範囲スライダー：配列を渡し、値ごとに Slider.Thumb をレンダリングします。SSR の位置合わせには index を追加します。
• 端での位置合わせが必要な場合は、thumbAlignment でサムの位置を調整します。

重要な禁止事項

• 入力、スライダー、スイッチ、ラジオグループにアクセシブルなラベルを付け忘れないでください。
• Base UI がデフォルトのスタイルを提供すると期待しないでください。独自のスタイルを適用してください。
• スタッキングやオーバーフローのコンテキストから抜け出す必要があるオーバーレイでは、Portal を忘れないでください。
• render の関数形式を使う場合、mergeProps を省略しないでください。

出力に関する要件

ユーザーへの回答には、以下を含めてください。

• 使用する具体的な Base UI コンポーネントと主要なパーツ。
• 簡潔な組み立て手順（必要に応じて Root + パーツ + ポータル／ポジショナー）。
• アクセシビリティと状態に応じたスタイリングの短いチェックリスト。

Links

• Documentation
• Releases
• GitHub
• npm