UI.MD

Combobox

An autocomplete input that combines a text input with a dropdown list of options.

Installation

$
npx shadcn@latest add https://ui.mattdowney.com/r/combobox.json

Usage

import { Combobox } from "@/components/ui/combobox"

Examples

Default

A searchable picker for a list too long to scan. Items are keyed by id, not value, and onSelect hands back the whole item rather than just its id.

With Meta

Items can carry meta secondary text (shown in mono) and a disabled flag.

With Create

Pass createLabel and onCreate to surface a create action below the list.

API Reference

PropTypeDefaultDescription
size"xs" | "sm" | "default" | "lg""default"Control height on the shared Button/Input ladder: 24 / 28 / 32 / 40, each with its matching action-radius rung. The same size on a Combobox, an Input and a Button gives one shape at one height.
items*ComboboxItem[]-The selectable options. Each item needs an id and label, plus optional meta (secondary text) and disabled.
value*string | number-The id of the currently selected item. Matched against each item to show the check indicator.
onSelect*(item: ComboboxItem) => void-Called with the full selected item. The popover closes after selection.
triggerLabel*string-Display label for the trigger button.
triggerMetastring-Secondary text shown after the trigger label.
searchablebooleanfalseShows a search input above the list for filtering options.
searchPlaceholderstring"Search..."Placeholder for the search input when searchable is set.
emptyTextstring"No results."Empty state text when no options match the search.
createLabelstring-Label for a create action pinned above the list. Requires onCreate; omit to hide.
onCreate() => void-Called when the create action is clicked. The popover closes afterward.
align"start" | "center" | "end""start"Alignment of the popover against the trigger.
classNamestring-Extra classes for the trigger button.