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.

Disabled and Invalid

disabled dims the trigger to 70% and blocks opening. aria-invalid adds the destructive border and ring; always put the error text beside the field so color is never the only signal.

Choose a framework to continue.

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[]NoneThe selectable options. Each item needs an id and label, plus optional meta (secondary text) and disabled.
value*string | numberNoneThe id of the currently selected item. Matched against each item to show the check indicator.
onSelect*(item: ComboboxItem) => voidNoneCalled with the full selected item. The popover closes after selection.
triggerLabel*stringNoneDisplay label for the trigger button.
triggerMetastringNoneSecondary 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.
createLabelstringNoneLabel for a create action pinned above the list. Requires onCreate; omit to hide.
onCreate() => voidNoneCalled when the create action is clicked. The popover closes afterward.
align"start" | "center" | "end""start"Alignment of the popover against the trigger.
disabledbooleanfalseBlocks opening and dims the trigger, the same way a disabled Select does.
aria-invalidbooleanNoneMarks the field as failing validation: destructive border, and a destructive ring on focus, as on Input and Select.
classNamestringNoneExtra classes for the trigger button.
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 | numberThe id of the currently selected item. Matched against each item to show the check indicator.
onSelect*(item: ComboboxItem) => voidCalled with the full selected item. The popover closes after selection.
triggerLabel*stringDisplay label for the trigger button.
triggerMetastringSecondary text shown after the trigger label.
searchableboolean = falseShows 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.
createLabelstringLabel for a create action pinned above the list. Requires onCreate; omit to hide.
onCreate() => voidCalled when the create action is clicked. The popover closes afterward.
align"start" | "center" | "end" = "start"Alignment of the popover against the trigger.
disabledboolean = falseBlocks opening and dims the trigger, the same way a disabled Select does.
aria-invalidbooleanMarks the field as failing validation: destructive border, and a destructive ring on focus, as on Input and Select.
classNamestringExtra classes for the trigger button.