Combobox

Installation#

# One-time setup (tokens + lib helpers)
npx koalaui-cli@latest init

# Add this component (its dependencies come along)
npx koalaui-cli@latest add combobox

Usage#

import {
  Combobox, ComboboxInput, ComboboxContent, ComboboxItem, ComboboxEmpty,
} from "@/components/ui/combobox"

export function Example() {
  const [value, setValue] = useState("")
  return (
    <Combobox value={value} onValueChange={setValue}>
      <ComboboxInput aria-label="Framework" placeholder="Pick a framework" />
      <ComboboxContent>
        <ComboboxItem value="next">Next.js</ComboboxItem>
        <ComboboxItem value="remix">Remix</ComboboxItem>
        <ComboboxEmpty />
      </ComboboxContent>
    </Combobox>
  )
}

Anatomy#

import {
  Combobox, Autocomplete, ComboboxInput, ComboboxContent, ComboboxItem,
  ComboboxGroup, ComboboxLabel, ComboboxSeparator, ComboboxEmpty, ComboboxStatus,
} from "@/components/ui/combobox"

<Combobox>            {/* or <Autocomplete> */}
  <ComboboxInput />
  <ComboboxContent>
    <ComboboxGroup>
      <ComboboxLabel />
      <ComboboxItem />
    </ComboboxGroup>
    <ComboboxSeparator />
    <ComboboxStatus />
    <ComboboxEmpty />
  </ComboboxContent>
</Combobox>

Icons and flags#

Rows take a leading icon like Select rows do, muted beside a medium label. Pass the picked option's glyph to prefix so the field shows it too. For countries, use Flag and match on the ISO code with keywords.

Groups#

ComboboxGroup with a ComboboxLabel heading, split by ComboboxSeparator. A group hides once all its rows filter out, and separators step aside while you type, so no orphan rules are left.

Clearable#

The clear button shows while the field holds text. It stays out of the tab order because Escape does the same from the keyboard. Turn it off with showClear={false}.

Async search#

Control inputValue to fetch as the user types, and pass filter={null} so the server's results show as they are. ComboboxStatus holds the list's place while a request is in flight and is announced politely.

Creatable#

Add a row for the typed text when nothing matches it exactly. Its textValue is the query, so the filter always keeps it, and picking it commits the new value like any other row.

Autocomplete#

Autocomplete takes the same parts, but the text is the value: anything typed is valid, and a suggestion only fills it in. Nothing is highlighted until you arrow down, so Enter keeps what you wrote. Rows carry no check.

Inside a Field#

In a Field, the label names both the field and the list, the hint is wired as its description, and hasError and disabled cascade. Pass name to post the value with the form.

Disabled#

disabled on the root locks the whole field. On a row, it stays visible but the keyboard skips it and a click does nothing.

Sizes#

size sets the field height on the shared control scale: sm 32, md 36, lg 40px, level with Input, Select and Button. Typed text stays 14px at every size.

Keyboard#

Focus never leaves the field. Arrow Down and Arrow Up open the list and move the highlight; Home and End jump to the ends while it is open. Enter picks the highlighted row. Escape first clears what you typed, then closes the list, then clears the value. Tab closes and moves on; leaving with exactly an option's text picks it, anything else reverts.

API reference#

FAQ#