All components (204)

Combobox

Fields · Combobox

What it is and when to use it

A field with a list of suggestions that also accepts free text: you type, the list filters, and you can pick an option or leave what you typed as it is. It is SearchField with allowsCustomValue switched on by default.

When to use it

A city, a category, a customer: there are suggestions, but anything else is valid too.
allowsCustomValue={false} turns it into a closed choice.

When not to

Several at once: MultiSelect (from a list) or TagsInput (without a list).

Keyboard and accessibility: those of SearchField (the ARIA combobox pattern).

What it looks like

Delivery city

If it's not in the list, type it in

Type “ma” and the list filters.

Only those in the list

Anything you type that is not in the list is discarded on leaving

<Combobox label="Delivery city" options={ciudades} hint="If it's not in the list, type it in" inputValue={texto} onInputChange={setTexto} />
<Combobox
  label="Only those in the list"
  options={ciudades}
  allowsCustomValue={false}
  hint="Anything you type that is not in the list is discarded on leaving"
/>

Props

Import it with import { Combobox } from '@amset/ui'. Required props are marked.

Prop	Type	What it does
`label`required	`string`	—
`options`required	`readonly ListOption[]`	—
`allowsCustomValue`	`boolean`	With `false` only an option from the list is valid: whatever is typed that does not match is discarded on leaving. `true` by default.
`autoFocus`	`boolean`	—
`className`	`string`	Merged with the library classes; it does not replace them.
`defaultInputValue`	`string`	—
`defaultSelectedKey`	`string \| null`	The key chosen at the start, without controlling it from outside.
`disabled`	`boolean`	—
`error`	`string`	—
`hiddenLabel`	`boolean`	The label for the screen reader only. For when the field sits inside something that already explains itself (a table cell, a group of filters), never to save space.
`hint`	`string`	—
`inputValue`	`string`	The typed text, controlled from outside.
`invalid`	`boolean`	—
`loading`	`boolean`	The options are arriving. Marks the field as busy, shows a ring and a `loadingText` row in the list; the options that were already there stay.
`loadingText`	`string`	What the loading row says. "Loading…" by default.
`menuTrigger`	`"input" \| "focus" \| "manual"`	What opens the list: `input` (the default) when typing, `focus` as soon as the field receives focus, and `manual` only with the button or the arrows.
`name`	`string`	So that the chosen key travels in a native form.
`noResultsMessage`	`string`	Text when what is typed finds nothing.
`offset`	`number`	Separation in pixels between the field and the list. By default, none.
`onBlur`	`() => void`	On leaving the field. The form uses it to mark that it has been touched.
`onInputChange`	`(text: string) => void`	—
`onOpenChange`	`(open: boolean) => void`	When the list opens or closes.
`onSelectionChange`	`(key: string \| null) => void`	—
`placeholder`	`string`	—
`placement`	`Placement`	Where the list appears. By default, right below the field.
`readOnly`	`boolean`	—
`renderOption`	`OptionRender<ListOption>`	Paints the inside of each option in the list: an avatar, two lines, a price. The name the screen reader reads is still `label`.
`required`	`boolean`	—
`selectedKey`	`string \| null`	The chosen key, controlled from outside.
`serverFiltered`	`boolean`	The list already comes filtered from outside (server-side search). By default the component itself filters with what is typed.
`size`	`"sm" \| "md" \| "lg"`	—
`validationBehavior`	`"aria" \| "native"`	—
`variant`	`FieldVariant`	—

It also accepts the attributes of the element it renders: className, style, data-*, aria-* and its events.

In the test bench

Every state and variant, to try one at a time, on its page at ui.amset.tech: