Novi UI
コンポーネント一覧

ComboBox

選択肢が 20 件を超えるならこちら。値が決まっていて自由入力を許したくないなら Select、一覧に無い値も受けるなら allowsCustomValue。

デモ

使い分け

こうする

  • 選択肢が 20 を超えるときに使う。文字で絞れる
  • 一覧に無い値を受けるかどうかを先に決める（allowsCustomValue）

こうしない

  • 選択肢が 5 つしかない欄に使わない。Select の方が全部見える
  • 一覧に無い値を黙って捨てない。受けないなら errorMessage で伝える

Props

ComboBox の props 一覧
名前型説明
variant'solid' | 'outline' | 'soft' | 'ghost' | 'plain'
size'sm' | 'md' | 'lg'
radius'none' | 'sm' | 'md' | 'lg' | 'full'
labelReactNode
placeholderstring
descriptionReactNode
errorMessageReactNode`isInvalid` のときに表示する。色だけに頼らずテキストを必ず伴う（WCAG 1.4.1）
namestring
selectedKeystring | null
defaultSelectedKeystring
onSelectionChange(key: string | null) => void
inputValuestring入力欄の文字列。制御したい場合に使う
defaultInputValuestring
onInputChange(value: string) => void
allowsCustomValueboolean一覧に無い文字列をそのまま値として残す。既定は選択肢に戻す
menuTrigger'focus' | 'input' | 'manual'一覧を開くきっかけ。既定は `input`（文字を打つと開く）
onOpenChange(isOpen: boolean) => void開閉の通知。開閉そのものは制御できない（React Aria の ComboBox は入力とキー操作から 開閉を導くため）。開きたいときは `menuTrigger="focus"` を使う
onKeyDownKeyboardEventHandler<HTMLInputElement>入力欄のキー操作。**IME 変換中のキーはここに届かない**（テーマが core の `useImeSafeKeys` を通す）。
isDisabledboolean
isReadOnlyboolean
isRequiredboolean
isInvalidboolean
childrenReactNode
classNamesClassNames<typeof comboBoxSlots>

Slot

構成部位に data-slot が出力されます。 CSS の上書きやテストはこれを狙ってください。

  • root必須
  • label
  • inputWrapper必須
  • input必須
  • trigger
  • icon
  • popover必須
  • listbox必須
  • option必須
  • description
  • errorMessage

アクセシビリティ

キーボード操作
キー動作
文字を打つ絞り込んで開く
↓ ↑開いて項目を移動
Enter決定
Escape閉じる
  • 入力欄は `role="combobox"`、一覧は `role="listbox"`。ArrowDown で開いて項目を移動、 Enter で決定、Escape で閉じる。IME 変換中の Enter と矢印キーは抑制される。 `description` と `errorMessage` は `aria-describedby` で関連付く
  • キーボードだけで操作できます。フォーカスリングはコントラスト比 3:1 以上です。
  • 本文のコントラスト比は light / dark とも 4.5:1 以上を検査で保証しています。
  • prefers-reduced-motion が有効なときはアニメーションを行いません。