Combobox
テキスト入力でコレクションを絞り込み、ポップアップから 1 つの意味のある項目値を確定します。
主なプロパティ
| プロパティ | 動作 |
|---|---|
| 状態 | 入力テキスト、選択値、開閉状態は、それぞれ制御付きまたは非制御で使用できます。 |
| 入力構造 | Field.Root が Field.Label と Combobox.Root を囲み、Root 内では InputGroup が任意の InputAdornment + Input + Clear + Trigger を並べ、Icon は Trigger 内に置きます。 |
| 複数選択構造 | Chips → Value → Chip + ChipRemove を使用し、グリッドコレクションは Collection → Row → Item で構成します。 |
| ポップアップ構造 | Portal → 任意の Backdrop + Positioner → Popup → Arrow + Status + List の順で、Group、Indicator、Separator、Collection、Empty を組み合わせます。 |
| 操作 | ポインター、矢印キー、Home/End、Enter、Escape、フィルター、フォーカスの復元、無効な項目、読み取り専用ルートは Base UI が処理します。 |
| フォーム | Root は name、form、required、disabled、readOnly、オブジェクトの直列化、ネイティブ検証、送信、リセットをサポートします。 |
インストール
pnpm add @tinyrack/ui長い行はコード領域を横にスクロールして確認できます。
スタイル
@import '@tinyrack/ui/components/combobox.css';長い行はコード領域を横にスクロールして確認できます。
インポート
import { TRCombobox } from '@tinyrack/ui/components/combobox';
import { TRForm } from '@tinyrack/ui/components/form';
import { TRField } from '@tinyrack/ui/components/field';
import { TRButton } from '@tinyrack/ui/components/button';長い行はコード領域を横にスクロールして確認できます。
プレイグラウンド
使用方法
例
サイズ パーマリンク
InputGroup に uiSize を渡して、Combobox の高さを隣の Input、NumberField、Button と揃えます。
フィルターの意味 パーマリンク
選択値と入力クエリを分けたまま、contains、startsWith、組み込みフィルターなしを比較します。
複数のチップとグリッドコレクション パーマリンク
Value は削除可能なチップを描画し、Collection と Row は公開グリッド構造を提供します。
制御状態とフィルターフック パーマリンク
クエリ、選択値、開閉状態を個別に制御し、ロケール対応のフィルター結果を useFilteredItems で読み取ります。
オーバーレイの構成 パーマリンク
Portal と Positioner は入力レイアウトを変えずにポップアップを固定します。Escape キーで閉じるとフォーカスが戻ります。
キーボード選択 パーマリンク
入力して絞り込み、矢印キーで移動し、Enter でハイライト中の項目を確定します。Escape で閉じます。
API
| サーフェス | 用途 |
|---|---|
Root | 項目、フィルター、単一・複数の値、入力テキスト、開閉状態、検証、フォームの直列化、ロケール、オブジェクトの比較と文字列変換を管理します。 |
InputGroup, InputAdornment, Input, Clear, Trigger, Icon | 編集可能なコントロールを構成します。InputAdornment は装飾で、Icon は Trigger 内に置きます。InputGroup は uiSize?: 'md' | 'lg' を渡して input、adornment、clear、trigger の高さを一括で調整できます。 |
Portal, Backdrop, Positioner, Popup, Arrow | 閉じることができるオーバーレイをマウントして配置します。Portal はカスタムコンテナーに対応し、インライン表示では省略できます。 |
Status, List, Group, GroupLabel, Collection, Row, Item, ItemIndicator, Separator, Empty | リストまたはグリッドのコレクションとアクセシブルなフィードバックを描画します。 |
Chips, Value, Chip, ChipRemove | 複数の選択値を表示・削除します。 |
useFilter, useFilteredItems | ロケール対応の contains、startsWith、endsWith 述語を作成し、Root 内でジェネリックなフィルタリング済み項目配列を読み取ります。 |
各パートには個別の TRCombobox* エクスポートとプロパティ・状態型があります。ルートアクション、状態変更とハイライトの詳細・理由型、TRComboboxFilter、TRComboboxFilterOptions もエクスポートします。
編集可能な Input は TRField.Root で囲み、TRField.Label で名前を付けます。ラベルは登録済みのコントロールから htmlFor を解決するため、id や useId を手動で指定する必要はありません。TRCombobox.Label はトリガーだけを使う選択構造専用です。InputGroup は uiSize?: 'md' | 'lg'(既定値 md) を受け取り、input、adornment、clear、trigger の高さを隣のコントロールと揃えます。無効なルートや項目は変更できません。読み取り専用ルートはフォーカスできますが、入力やクリアはできません。オブジェクト値は安定した同一性を保ち、{ label, value } 規約で足りない場合は itemToStringLabel、itemToStringValue、isItemEqualToValue を指定します。
Combobox モジュールは SSR でも安全です。Portal はハイドレーション後にマウントされるため、サーバーとクライアントで制御付きの初期値を一致させる必要があります。スタイルは combobox.css で別途提供されます。--tr-combobox-input-background、--tr-combobox-content-background、--tr-combobox-content-max-height、--tr-combobox-content-max-width、--tr-combobox-option-min-height で外観を調整でき、ライト・ダークのセマンティックトークンへフォールバックします。