Combobox

テキスト入力とドロップダウン選択を組み合わせた高度な入力。多数の選択肢からキーワードで絞り込んで決定する。

プレビュー(動作デモ)

実際にフィールドに入力するとメニューが絞り込まれます。↑↓ で項目移動、Enter で決定、Esc で閉じる、Tab でハイライト中の項目をコミットして移動。

単一選択: 顧客検索 (150 件)

選択中: (未選択)

複数選択: 顧客タグ

重要顧客要折返し

選択中 (2 件): 重要顧客 / 要折返し

フィールド内に直接チップが追加されます。タグが増えると下方向に折り返します。空のときに Backspace で末尾を削除できます。

縦幅

縦幅は固定せず、入力された内容(タグ数・改行)に応じて自動拡張する(content-hugging)。最小値のみ定義する。

項目	値
最小高さ	40px(標準コンポーネント高さ、Button M と同じ)
上限	設けない(複数選択タグが増えるほど高くなる)

横幅

横幅は固定の variant を持たず、配置時にフォーム列幅やレイアウトに応じて決める。

項目	値
最小幅	320px
最大幅	親要素いっぱい(100%)

長い検索キーワードや候補ラベルが多い用途では幅を広めに取る。フォーム列内で他の入力と並ぶ場合は列幅に追従させる。

状態

Normal

Focus

Error

Disabled

単一選択

"use client";
import { useState } from "react";
import { Combobox } from "@/components/Combobox";

const OPTIONS = [
  { value: "1", label: "選択肢 1" },
  { value: "2", label: "選択肢 2" },
  { value: "3", label: "選択肢 3" },
];

export function Example() {
  const [value, setValue] = useState<string | null>(null);
  return (
    <Combobox
      label="選択"
      options={OPTIONS}
      value={value}
      onChange={setValue}
      placeholder="選択または入力"
    />
  );
}

仕様

寸法・構造

幅: 最小 320px / 最大親要素いっぱい(横幅セクション参照)
高さ: 最小 40px、内容に応じて自動拡張(縦幅セクション参照) / radius 4px
左にネイティブ <input type="text">、右に ▼/▲ トグル領域(左に 1px 区切り線)
Normal: 1px gray border / Open: 2px blue border / Error: 1px red border / Disabled: gray bg + text-disabled
メニュー: トリガー直下 2px / トリガー幅に追従 / radius 8px / shadow 0 2px 4px 1px rgba(31,41,55,0.30) (LAYER2) / max-height 320px でスクロール

挙動

入力に応じて選択肢を case-insensitive substring で絞り込み (filterFn で差し替え可)
未一致のとき「該当する項目がありません」を表示 (emptyMessage で差し替え可)
選択中の項目ラベルと入力欄が一致しているときは「ブラウズ状態」とみなし、すべての項目を再表示
外側クリック / Esc で入力欄が前回確定値に戻る

キーボード操作

フォーカス + 文字入力 / ↑↓ でメニューを開く
↑↓ で項目移動、Home/End で先頭/末尾、Enter で決定、Esc で破棄して閉じる
Tab: ハイライト中の項目をコミットして次のフォーカスへ

アクセシビリティ

WAI-ARIA combobox パターン: role="combobox" + aria-expanded + aria-controls + aria-activedescendant
メニューは role="listbox"、項目は role="option" + aria-selected
エラー時は aria-invalid="true"

利用基準

使うべき時

選択肢が多すぎてスクロールでは目的に到達しにくい場合 (検索でショートカット)
担当者選択・外部連携項目マッピングなど膨大な候補からの抽出
現在のドメインで一意な属性 (顧客タグ) の付与

使わない時

選択肢が 5 個以下で単一選択 → Select / Radio Button を使用
都道府県など追加・拡張のない閉じた列挙 → Select を使用
オン/オフの切り替え → Toggle Switch / Checkbox を使用

Figma

Figma で Combobox コンポーネントを開く ↗