Combobox Field

Use ComboboxField when people need 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. Use another component for multiple selection.

Select 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. Clearing 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

Use errorMessage to render a validation message. Pass server errors through React Aria Form.

import { Form } from 'react-aria-components';

<Form validationErrors={{ country: 'Please select a country.' }}>
	<ComboboxField
		errorMessage={(validation) => validation.validationErrors.join(' ')}
		label="Country"
		name="country"
	>
		{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
	</ComboboxField>
</Form>;

Groups

Use ComboboxSection to group related static options.

Async results

Pass items and loadingState when results load or filter asynchronously. If the list is empty while loading or filtering, 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 and popoverProps configure the underlying listbox and popover. menuWidth sets the popover width.

Mobile behaviour

Below the small breakpoint (640px), options appear in a bottom tray instead of a positioned popover. The tray follows the visual viewport so it stays above the on-screen keyboard. 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.

Primitive

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