combobox

Installation

Import combobox primitives (and optionally `ComboboxSelect`) from `@/components/kamod-ui/combobox`.

pnpm add @kamod-ch/ui

Usage

`Combobox` supports single or `multiple` selection (`value` / `onValueChange` as `string` or `string[]`). `liftedFilter` shares the filter string between `ComboboxInlineInput` or `ComboboxChipsInput` and the list (`Command` stays mounted via `forceMount` on content). Set `autoHighlight` on the root (or `ComboboxCommand`) for first-match highlight plus ArrowUp/Down and Enter — works in `ComboboxInput`, `ComboboxInlineInput`, and `ComboboxChipsInput` via `commandNavRef`. `showClear` + `ComboboxClear` clears selection and filter. Multi-select: `ComboboxChips` + `ComboboxChip` + `ComboboxChipsInput` (implies `liftedFilter`). `ComboboxSelect` maps props to these patterns (`liftedFilter`, `multiple`, `showClear`, `autoHighlight`).

import { Combobox } from "@/components/kamod-ui/combobox";

<Combobox />

Basic

String list, default selection, chevron on the trigger.

Preset: ComboboxSelect

Shortcut for `options: { label, value }[]` — replaces the legacy single-file combobox.

Controlled

`value` + `onValueChange`; optional checkmark for the active row.

value: en

Popup (Button trigger)

`ComboboxTrigger asChild` with `Button variant="outline"` — search field lives in the content panel (shadcn popup pattern).

Custom row content

`Item` + `ItemTitle` / `ItemDescription` inside `ComboboxItem` (shadcn custom items).

Groups + separator

Grouped timezones with `ComboboxGroup` and `ComboboxSeparator` between sections.

Invalid

`aria-invalid` on the trigger for error styling (pairs with Field invalid state).

Disabled

`disabled` on `Combobox` disables the trigger.

Auto-highlight + keyboard

`autoHighlight` on `Combobox`: first visible row is highlighted on filter; ArrowUp/Down moves; Enter activates (via `Command`).

Clear button (preset)

`ComboboxSelect` with `showClear` — `ComboboxClear` resets selection (and filter when lifted).

Inline input trigger (Base UI style)

`ComboboxSelect` with `liftedFilter` + `autoHighlight`: visible field is the filter; list opens below; optional `showClear`.

Multi-select + chips

`ComboboxSelect` with `multiple`: chip row + `ComboboxChipsInput`; `onValueChange` receives `string[]`.

Next.js

value: ["next"]

API Reference

Props, slots and variants for this component.

Combobox component props and accepted values.

Prop	Type	Default
Combobox items	`readonly unknown[]`	`[]`
Combobox multiple / liftedFilter / autoHighlight / showClear	`boolean`	`false`
Combobox value / defaultValue / onValueChange	`string \| string[]`	`—`
ComboboxItem item	`unknown (row payload)`	`required`
ComboboxList children	`(item, index) => vnode`	`—`
ComboboxSelect	`liftedFilter, multiple, showClear, autoHighlight`	`—`
Command autoHighlight	`boolean`	`false`

Accessibility Notes

Associate a visible `Label` with the trigger id when used in forms. The filter input inside the popover should have a clear placeholder; announce errors via `aria-invalid` on the trigger when validation fails.