mantine-combobox

Mantine Combobox スキル

Mantine 9.x 向けに書かれています。

概要

Combobox は、あらゆるセレクトのような UI を構築するための低レベルプリミティブを提供します。組み込みの Select、MultiSelect、Autocomplete、TagsInput コンポーネントは、すべてこの上に構築されています。

まず既製のコンポーネントを確認する

次のいずれにも当てはまらない場合に限り、Combobox プリミティブを使って構築してください。

要件	使用するもの
標準のセレクト、マルチセレクト、オートコンプリート、またはタグ入力	Select、MultiSelect、Autocomplete、TagsInput（すべて renderOption をサポート）
ボタンやその他の要素に紐づくオプションのドロップダウン（入力欄なし）	ComboboxPopover（データ駆動型：data、value、onChange、searchable、multiple）
階層型のオプション	TreeSelect（下記参照）
数百件を超えるオプション	useVirtualizedCombobox を使った Combobox。仮想化パターンを参照してください

<ComboboxPopover data={['React', 'Angular', 'Vue']} value={value} onChange={setValue}>
  <ComboboxPopover.Target>
    <Button variant="default">{value || 'Select framework'}</Button>
  </ComboboxPopover.Target>
</ComboboxPopover>

ComboboxPopover はターゲットをクリックすると自動で開き、選択中のオプションにチェックアイコンを表示し、キーボード操作によるナビゲーションを処理します。便利なプロパティ：searchable、multiple（値が string[] になり、選択中はドロップダウンが開いたままになります）、allowDeselect={false}（常に1つのオプションが選択された状態になります）、nothingFoundMessage、renderOption、limit、maxDropdownHeight、name（フォーム用の非表示入力欄）、comboboxProps={{ width: 220, position: 'bottom-start' }}。data は Select と同様に、無効化された項目やグループをサポートします：[{ group: 'Size', items: [{ value: 'xs', label: 'XS' }] }]。タブ、ヘッダー、フッター、作成アクションなどのカスタムドロップダウンコンテンツはレンダリングできません。その場合は Combobox プリミティブを使用してください。

TreeSelect はネストされた data（{ value, label, children? }[]、値は一意である必要があります）を受け取り、ドロップダウン内に展開可能なツリーを含む入力欄を表示します。プロパティには mode（単一選択、複数選択、または親子連動のチェックボックス）、searchable、clearable、renderNode があります。葉ノードのみを選択可能にする、完全なパスを含む検索結果をフラットリストで表示する、またはボタンをトリガーにするなど、異なるレイアウトが必要な場合は、代わりに Combobox プリミティブでツリーを構築してください。その場合は、表示される各行を Combobox.Option としてレンダリングし、その行を選択するか展開するかを onOptionSubmit で判断します。

基本的なワークフロー

1. ストアを作成する

const combobox = useCombobox({
  onDropdownClose: () => combobox.resetSelectedOption(),
  onDropdownOpen: () => combobox.selectFirstOption(),
});

2. 構造をレンダリングする

<Combobox store={combobox} onOptionSubmit={handleSubmit}>
  <Combobox.Target targetType="button">
    <InputBase
      component="button"
      type="button"
      pointer
      rightSection={<Combobox.Chevron />}
      onClick={() => combobox.toggleDropdown()}
    >
      {value || <Input.Placeholder>Pick value</Input.Placeholder>}
    </InputBase>
  </Combobox.Target>
  <Combobox.Dropdown>
    <Combobox.Options>
      {options.map((item) => (
        <Combobox.Option value={item} key={item}>{item}</Combobox.Option>
      ))}
    </Combobox.Options>
  </Combobox.Dropdown>
</Combobox>

3. 送信を処理する

const handleSubmit = (val: string) => {
  setValue(val);
  combobox.closeDropdown();
};

ターゲットの種類

シナリオ	使用するもの
ボタンをトリガーにする（テキスト入力なし）	<Combobox.Target targetType="button">
入力欄をトリガーにする	<Combobox.Target>（デフォルト）
ピルと独立した入力欄（複数選択）	<Combobox.DropdownTarget> + <Combobox.EventsTarget>

Combobox が提供する機能

• ターゲットがキーボード操作を処理します。ArrowUp／ArrowDown でハイライトを移動し、無効なオプションをスキップします（ドロップダウンが閉じている場合は開きます）。Enter でハイライトされたオプションを送信し、Escape でドロップダウンを閉じます。targetType="button" の場合は、Space と Enter でも開きます。Tab は処理されません。
• オプションがハイライトされていない場合、Enter は何もしないため、自由入力フィールドで独自に処理できます。
• ユーザーが矢印キーを押すまで、オプションはハイライトされません。ただし、selectFirstOption() または selectActiveOption() を呼び出した場合は除きます。
• オプションをクリックしても入力フィールドからフォーカスは移動せず、無効なオプションが onOptionSubmit を呼び出すこともありません。
• Combobox.Option は data-* 属性とイベントハンドラーをその要素に渡します。
• Combobox.Search はターゲットと同じキーを処理します。ターゲットの子要素または Combobox.Search に設定した独自の onKeyDown が先に呼び出され、その後に組み込みの処理が実行されるため、追加のキー（PageUp、ArrowRight）をそこで追加できます。キーボード操作を完全に引き継ぐ場合（矢印キーでキャレットを移動する必要があるテキストエリアなど）は、Combobox.Target で withKeyboardNavigation={false} を設定し、selectNextOption、selectPreviousOption、clickSelectedOption を自分で呼び出します。
• デフォルトでは、ドロップダウンの幅はターゲットと同じ（width="target"）で、ポータルにレンダリングされ、閉じている間もマウントされたままになり、アニメーションなしで開きます。また、オプションにカーソルを合わせてもキーボードのハイライトは変わりません。
• ドロップダウンはモーダルやドロワーより上のポータルにレンダリングされ、それらによってクリップされません。Modal 内では、Escape を押すとドロップダウンだけが閉じ、もう一度押すとモーダルが閉じます。追加のコードは必要ありません。
• オプションは値を選択するものでなくてもかまいません。onOptionSubmit は切り替えや行の展開、アクションの実行などを行い、ドロップダウンを閉じるかどうかを独自に決定できます。
• ドロップダウン内のその他のインタラクティブなコンテンツ（Combobox.Header 内のボタンや Retry リンクなど）は処理されません。入力フィールドのフォーカスを維持し、onBlur ハンドラーによってドロップダウンが閉じないように、そこへ onMouseDown={(event) => event.preventDefault()} を追加してください。

混同しやすい 2 つの用語：

• **選択中（selected）**のオプション：キーボード操作でハイライトされているオプションです（data-combobox-selected）。
• **アクティブ（active）**なオプション：現在の値を持つオプションで、active プロパティ（data-combobox-active）で示されます。デフォルトのスタイルはないため、チェックアイコンを表示してください。

参考資料

上記の基本的な選択機能を超えるものを作成する前に、両方をお読みください。

• references/patterns.md — 完全なサンプル：検索可能な選択（入力フィールドをトリガーに使用）、候補付き自由入力フィールド、テキストエリア向けの候補（メンション）、CSS モジュールを使ったカスタムスタイル、数千件のオプションに対応する仮想化リスト、Combobox を基にしたカスタムフォーム入力、ドロップダウン内の検索、ピル付きの複数選択、作成可能なオプション、読み込み中・エラー状態に対応する非同期検索、グループ、カスタムオプションのレンダリング、開いたときに現在の値をハイライト表示、クリアボタン、フォームとの連携、ビューポートに収まるドロップダウン
• references/api.md — useCombobox のオプションと各ストアメソッドの機能、デフォルトのスタイルとその上書き方法、useVirtualizedCombobox、すべてのサブコンポーネントのプロパティ、CSS 変数、Styles API セレクター

情報の検索

参考資料に必要な情報がない場合は、推測しないでください。

• Mantine MCP サーバー（@mantine/mcp-server）が接続されている場合は、search_docs と get_item_doc を使用してください。
• それ以外の場合は https://mantine.dev/llms.txt を取得して、Combobox のページを開いてください。https://mantine.dev/combobox/ には、完全なサンプルが 50 件以上あります。