Combobox

PreviewCode

Installation

CLIManual

pnpmnpmyarnbun

pnpm dlx shadcn@latest add @kaui/combobox

Usage

import { Combobox } from "@/components/ui/combobox";
import type { SelectionOption } from "@/hooks/use-filtered-options";

const options: SelectionOption<string>[] = [
  { value: "react", label: "React" },
  { value: "vue", label: "Vue" },
];

<Combobox
  items={options}
  selected={selected}
  onSelectedChange={setSelected}
  placeholder="Search..."
  closeAfterSelect
/>;

Each option is { value: T, label: string, disabled?: boolean }. The generic T extends string so you can keep values fully typed.

Examples

Input Addons

Use startAddon and endAddon to embed any element inside the input , a search icon, a clear button, a status indicator. The slots are rendered inside InputGroup so they align and interact correctly with the text field.

PreviewCode

Async Search

Wire onQueryChange to a debounced fetch, set disableLocalFilter so the component shows whatever you pass in items, and toggle isLoading while the request is in flight. The skeleton appears in place of the list until results arrive.

PreviewCode

Custom Option Rendering

Pass renderOption to take full control of how each item looks. Receives the option object and a boolean for selected state , use them to show icons, badges, or secondary text.

PreviewCode

Create New Option

Use emptyContent with a controlled query to show an inline “Add” action when no results match. onMouseDown on the button prevents the input from blurring (which would close the dropdown before the click fires).

PreviewCode

Grouped Options

Pass a ComboboxGroup<T>[] to items to render options under labeled headings. Groups filter independently — a group is removed entirely if none of its items match the query. The flat SelectionOption<T>[] form still works as before.

PreviewCode

Footer Item

Pass footerItem to pin a persistent action at the bottom of the list. Unlike emptyContent, it is fully keyboard-navigable and always visible while the dropdown is open — regardless of whether results exist.

The canonical use case is a server-search field where the user can either pick a suggestion or submit the raw typed phrase as a full-text search. Conditionally returning undefined when the query is empty keeps the item hidden until the user has typed something.

PreviewCode

Props

Prop	Type	Default	Description
selected	SelectionOption<T> | null	—	Required. The currently selected option, or null
onSelectedChange	(value: SelectionOption<T> | null) => void	—	Required. Called when selection changes; receives null on deselect
items	SelectionOption<T>[] \| ComboboxGroup<T>[]	—	Required. Flat list of options, or grouped via ComboboxGroup<T> (\{ label?: string; items: SelectionOption<T>[] \})
open	boolean	—	Controlled open state. Omit to let the component manage it
onOpenChange	(open: boolean) => void	—	Called whenever the dropdown opens or closes
query	string	—	Controlled search query. Omit for uncontrolled
onQueryChange	(query: string) => void	—	Called whenever the search input changes
placeholder	string	"Search..."	Placeholder text shown in the search input
closeAfterSelect	boolean	false	Close the dropdown immediately after an option is selected
disableLocalFilter	boolean	—	Skip client-side filtering. Use when items are already filtered server-side
filterFn	(item: SelectionOption<T>, query: string) => boolean	—	Custom filter predicate. Replaces the default case-insensitive label match
isLoading	boolean	false	Show the loading state in place of the option list
emptyContent	ReactNode	"No results found."	Content shown when no options match the query
loadingContent	ReactNode	Skeleton bar	Content shown in place of the list while isLoading is true
renderOption	(option: SelectionOption<T>, selected: boolean) => ReactNode	—	Custom renderer for each list item
startAddon	ReactNode	—	Leading addon rendered inside the input (e.g. a search icon)
disabled	boolean	false	Disable the entire combobox — input is non-interactive and the dropdown cannot open
clearable	boolean	false	Show a built-in × button when an option is selected. Clears both the selection and the query.
endAddon	ReactNode	—	Trailing addon rendered inside the input (e.g. a status indicator). Rendered alongside the clearable button when both are present.
footerItem	\{ label: ReactNode; onSelect: () => void \}	—	A persistent action pinned to the bottom of the list. Keyboard-navigable (arrow keys + Enter). Shown whenever the dropdown is open. Pass undefined conditionally to hide it.

All PopoverContent props (align, side, sideOffset, etc.) are also accepted and forwarded to the dropdown.