Combobox

Once a dropdown has more than a handful of options, people want to type to find one. This Combobox treats CJK input as a first-class case: while someone types Zhuyin such as "ㄊㄞˊ", the list stays put instead of jumping around on half-typed syllables, and filtering only happens once a character is picked. Enter, arrow keys, and Backspace pressed mid-composition all go to the IME, so nothing is selected or removed by accident. The default matcher treats 臺 and 台 as the same character, and keywords let you add English names or aliases. The list is anchored below the input and flips above when there is no room, and the highlight slides between options. Switch on multiple and selected items become removable chips; creatable lets people add items that are not in the list.

Playground

Tune the props live — the code snippet updates as you go, so you can dial in the look you want before copying it.

import * as React from "react";

export default function Example() {
  return (
    <div className="flex min-h-[320px] w-full items-center justify-center p-6">

<Combobox/>

    </div>
  );
}

Installation

Usage

import { Combobox, type ComboboxOption } from "@/components/ui/combobox";

const cities: ComboboxOption[] = [
  { value: "taipei", label: "臺北市", group: "北部", keywords: ["Taipei"] },
  { value: "taichung", label: "臺中市", group: "中部", keywords: ["Taichung"] },
  { value: "kaohsiung", label: "高雄市", group: "南部", keywords: ["Kaohsiung"] },
];

// 單選：value 為 string | null
const [city, setCity] = React.useState<string | null>(null);
<Combobox options={cities} value={city} onValueChange={setCity} aria-label="配送縣市" />;

// 多選 + 可新增：value 為 string[]
const [tags, setTags] = React.useState<string[]>([]);
const [tagOptions, setTagOptions] = React.useState<ComboboxOption[]>([
  { value: "設計", label: "設計" },
  { value: "前端", label: "前端" },
]);
<Combobox
  multiple
  creatable
  options={tagOptions}
  value={tags}
  onValueChange={setTags}
  onCreate={(label) => setTagOptions((prev) => [...prev, { value: label, label }])}
  maxVisibleChips={3}
  aria-label="感興趣的主題"
/>;

Props

ComboboxOption

The ComboboxOption, ComboboxSide, ComboboxProps, ComboboxSingleProps, and ComboboxMultipleProps types are also named exports.

How it works

• No filtering mid-composition: the component tracks composition with compositionstart / compositionend. While composing, the input shows the Zhuyin as usual, but the text used for filtering is frozen at its pre-composition value and only updates with the final text once a character is picked — the list never flickers on partial syllables like "ㄊㄞ"
• Keys mid-composition belong to the IME: Enter, ↑/↓, Backspace, and Esc all check isComposing and keyCode 229 first (Safari sends keydown after compositionend), and are passed through to the IME while composing, so nothing is selected and no chip is removed by accident
• When it opens and closes: clicking the input, starting to type, pressing ↓, or clicking the chevron button opens the list; the first Esc closes it and the second clears the input; clicking outside or tabbing away closes it. In single mode the input shows the chosen label after selection; on blur, edited-but-unchosen text is restored to the selected label; clicking the selected option again deselects it
• Positioning: the list is portaled to body with position: fixed, matches the width of the input frame (including the chip row in multiple mode), and flips above when there is no room below. Scrolling and resizing recompute the position, throttled with rAF, and the list stays hidden until first measured so it never flashes in the corner
• Timing: the pop-in is fade + scale 0.95 + an 8px slide along the side, 100ms by default and controlled by duration; CSS transitions inside the list read --wb-combobox-duration, which you can override globally. The highlight slides on a shared-layoutId spring; chips spring in, and the remaining chips FLIP into place when one is removed
• Creating: with creatable, if the typed text doesn't exactly match any existing label (again treating 臺 as 台), a Create row appears at the bottom of the list; Enter or a click triggers onCreate

Accessibility

• The input has role="combobox" with aria-expanded, aria-controls, and aria-autocomplete="list", and aria-activedescendant points at the highlighted option; focus always stays in the input and clicking the list never blurs it
• The list is role="listbox" (with aria-multiselectable in multiple mode); options are role="option" with aria-selected and aria-disabled; groups are wrapped in role="group" and named by their heading
• ↑/↓ move the highlight cyclically and skip disabled options, Home/End jump to the first and last option, and Enter selects; in multiple mode, Backspace in an empty input removes the last chip
• Every chip's remove button is a Tab-focusable button with an aria-label of "Remove xxx"; the result count is announced through an aria-live="polite" region ("N results" or the empty-state text)
• When the user has "reduce motion" enabled, the list keeps only its fade (same duration) with no scale or slide; the highlight and chips jump straight into place without springs or FLIP reflow