Combobox Field

Single-select combobox field with label, validation, and async options.

Use ComboboxField for a single-select combobox with label, description, error, popover, listbox, and optional async loading built in.

Best practices

API shape

• Root props follow React Aria ComboBox naming.
• Composed convenience props include label, description, errorMessage, necessityIndicator, size, and placeholder.
• children renders items from items or defaultItems.
• listBoxProps and loadMoreItem are lower-level escape hatches.

Selection indicators

The selected option shows a checkmark in the listbox. When the control has a selection, it shows a clear button before the trigger. Pressing the clear button clears the selection and input text.

The clear button is omitted when the field is disabled or read-only.

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

Required fields

Use isRequired with necessityIndicator to show that the field is mandatory.

Validation

Pass field-level validation through React Aria Form. Use errorMessage to render the validation message.

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

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

Grouped options

Use ComboboxSection to group related options inside the listbox.

Async options

Pass loadingState for built-in loading and empty states. Control the option collection with items.

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

Infinite scroll

Use onLoadMore for automatic sentinel-based loading, or loadMoreItem when you need full control over the load-more row.

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

Mobile tray

Below the small breakpoint (640px) the popover renders as a bottom tray instead of a positioned popover, following Adobe Spectrum's combobox pattern. The tray spans the full viewport width, slides up from the bottom edge on open and back down on close, and keeps clear of the on-screen keyboard using the Visual Viewport API. A scrim dims the page behind the tray, and a grab-handle affordance marks its top edge. In browsers that support calc-size(), the tray keeps a usable minimum height even when the viewport is cramped, while still hugging shorter lists instead of leaving empty space.

Accessibility

The tray's slide transition (and the desktop popover's fade) is disabled for users who request prefers-reduced-motion: reduce.

Primitive

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

Props