Combobox Field

Use ComboboxField when someone needs to search for or choose one option from a list. It combines an input, label, description, validation message, popover, and listbox.

Items and selection

Use defaultItems for a static collection. Use items with loadingState when results load or filter asynchronously. ComboboxField supports one selected value.

Choose and clear an option

Pass static children or a render function to create options. The listbox marks the selected option. When there is a selection, the field shows a clear button before the trigger. The clear button removes the selection and input text. The clear button is unavailable for disabled and read-only fields.

<ComboboxField defaultItems={countries} defaultValue="ca" label="Country" name="country">
	{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
</ComboboxField>

Required fields

Set isRequired to make a selection mandatory. Use necessityIndicator to choose how it appears beside the label.

Validation

Set isRequired or pass validate to check the selected value. ComboboxField shows its validation message after validation fails. Pass errorMessage only for an error you already have, such as one from a form library or your server. A non-empty message marks the field invalid. Read Validation for where messages come from, server errors, and how to write them.

Groups

Use ComboboxSection to group related static options.

Size

Use size to set the control height and typography. Use small in compact layouts. medium is the default.

Async results

Pass items and loadingState when results load or filter asynchronously. If the list is empty while it loads or filters, the field shows a loading indicator. An empty completed result shows “No results”.

<ComboboxField
	items={results}
	label="Country"
	loadingState={status}
	name="country"
	onInputChange={setQuery}
>
	{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
</ComboboxField>

Pass onLoadMore for incremental results. It adds the built-in load-more row and spinner. Use loadMoreItem when that row needs custom content. listBoxProps configures the underlying listbox. popoverProps and menuWidth configure the desktop popover, which mobile replaces with a tray.

Mobile behaviour

ComboboxField checks the device screen width, not the browser viewport width. Narrowing a desktop browser window does not switch to the tray.

Below the bp640 breakpoint, the field shows a button that displays the selected option. Someone taps the button to open a modal tray with a focused search input. The tray has a fixed height and locks page scroll. The tray motion and desktop popover fade respect reduced-motion preferences.

Accessibility

Provide a visible label where possible. The field passes React Aria combobox interactions and form semantics to its input, trigger, listbox, and validation message.

Related components

Use the combobox primitives when you need a custom combobox layout.

API