FORMS

Combobox

Searchable single-select. Trigger looks like Select; the dropdown content uses cmdk for fuzzy matching plus the Damo Memphis chrome on the popover.

Import

import { Combobox } from 'damo-ui'

Basic usage

1<Combobox
2  options={[
3    { value: 'it', label: 'Italy' },
4    { value: 'fr', label: 'France' },
5    { value: 'de', label: 'Germany' },
6    { value: 'us', label: 'United States' },
7    { value: 'br', label: 'Brazil' },
8  ]}
9  placeholder="Pick a country"
10/>

Controlled

Manage the selection externally for validation or persistence.

1function ControlledExample() {
2  const [value, setValue] = useState<string>()
3  return (
4    <Combobox
5      options={LANGUAGES}
6      value={value}
7      onValueChange={setValue}
8      searchPlaceholder="Type to search…"
9      emptyMessage="No matches"
10    />
11  )
12}

Props

Combobox props
PropTypeDefaultDescription
options*ComboboxOption[]—Items to render — { value, label, disabled? }.
valuestring—Controlled selected value. Pair with onValueChange.
defaultValuestring—Uncontrolled initial selected value.
onValueChange(value: string) => void—Fires when an option is picked.
placeholderReactNode'Scegli…'Trigger text shown when nothing is selected.
searchPlaceholderstring'Cerca…'Placeholder inside the search input.
emptyMessageReactNode'Nessun risultato'Shown when the search yields no results.
disabledboolean—Disables the trigger.
idstring—id forwarded to the trigger button (label association).
classNamestring—Tailwind classes merged onto the trigger.

Combobox vs Select

  • Reach for Combobox when the option list is long enough that scrolling alone is friction (≥ ~10 options) or when users will search by typed input.
  • Reach for Select for short lists (2-9 items) where keyboard arrow navigation is sufficient.

Native form submission

Combobox renders a <button> + popover with no hidden form input and no name prop. To submit through a traditional <form>, manage the value with React state and either render your own hidden input or read it from the submit handler.

Accessibility

  • The trigger is a plain <button> (no role="combobox") with aria-expanded reflecting the popover state. This is a button-plus-popover pattern, not the full WAI-ARIA combobox pattern that Select provides.
  • The dropdown list is rendered by cmdk: type to filter, arrows to move, Enter to select, Esc to close.
  • Use FormField or pair id with a sibling Label so screen readers announce the field name.
← DatePickerPopover →