Forms

Combobox Field

Searchable single-select field with label, validation, and option list.

React Aria SourceView as Markdown Edit on GitHub

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.

Combobox Field: Basic

Open in playground

Favourite fruit

import { ComboboxField, ComboboxItem } from '@luke-ui/react/combobox-field';
import { Stack } from '@luke-ui/react/stack';

type Fruit = { id: string; label: string };

const fruits: Array<Fruit> = [
	{ id: 'apple', label: 'Apple' },
	{ id: 'orange', label: 'Orange' },
	{ id: 'banana', label: 'Banana' },
	{ id: 'grape', label: 'Grape' },
];

export default () => {
	return (
		<Stack gap="space.16">
			<ComboboxField
				defaultItems={fruits}
				defaultValue="apple"
				label="Favourite fruit"
				name="fruit"
				placeholder="Choose a fruit"
			>
				{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
			</ComboboxField>
		</Stack>
	);
};

Combobox Field: Basic

Loading Combobox Field: Basic example

Items and selection

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

Pass static children or a render function to create options. @luke-ui/react/combobox-field exports ComboboxItem and ComboboxSection alongside the field. 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. Read Required fields for the indicator values.

Combobox Field: Required

Open in playground

Work location

Choose the country where you work.

import { ComboboxField, ComboboxItem } from '@luke-ui/react/combobox-field';

const countries = [
	{ id: 'australia', label: 'Australia' },
	{ id: 'canada', label: 'Canada' },
	{ id: 'new-zealand', label: 'New Zealand' },
	{ id: 'united-states', label: 'United States' },
];

export default () => {
	return (
		<ComboboxField
			defaultItems={countries}
			description="Choose the country where you work."
			isRequired
			label="Work location"
			name="workLocation"
			necessityIndicator="required-asterisk"
			placeholder="Choose a country"
		>
			{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
		</ComboboxField>
	);
};

Combobox Field: Required

Loading Combobox Field: Required example

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.

Combobox Field: Validation

Open in playground

import { Button } from '@luke-ui/react/button';
import { Cluster } from '@luke-ui/react/cluster';
import { ComboboxField, ComboboxItem } from '@luke-ui/react/combobox-field';
import { Stack } from '@luke-ui/react/stack';
import type { SubmitEvent } from 'react';

const countries = [
	{ id: 'australia', label: 'Australia' },
	{ id: 'canada', label: 'Canada' },
	{ id: 'new-zealand', label: 'New Zealand' },
	{ id: 'united-states', label: 'United States' },
];

function handleSubmit(event: SubmitEvent<HTMLFormElement>) {
	event.preventDefault();
}

export default () => {
	return (
		<form onSubmit={handleSubmit}>
			<Stack gap="space.16">
				<ComboboxField
					defaultItems={countries}
					isRequired
					label="Country"
					name="country"
					placeholder="Choose a country"
				>
					{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
				</ComboboxField>
				<Cluster>
					<Button type="submit">Submit</Button>
				</Cluster>
			</Stack>
		</form>
	);
};

Combobox Field: Validation

Loading Combobox Field: Validation example

Groups

Use ComboboxSection to group related static options.

Combobox Field: Grouped options

Open in playground

Produce

import { ComboboxField, ComboboxItem, ComboboxSection } from '@luke-ui/react/combobox-field';

export default () => {
	return (
		<ComboboxField defaultValue="apple" label="Produce" name="produce" placeholder="Choose produce">
			<ComboboxSection title="Fruit">
				<ComboboxItem id="apple">Apple</ComboboxItem>
				<ComboboxItem id="orange">Orange</ComboboxItem>
			</ComboboxSection>
			<ComboboxSection title="Vegetables">
				<ComboboxItem id="carrot">Carrot</ComboboxItem>
				<ComboboxItem id="potato">Potato</ComboboxItem>
			</ComboboxSection>
		</ComboboxField>
	);
};

Combobox Field: Grouped options

Loading Combobox Field: Grouped options example

Size

Use size to set the control height and typography. Use small in compact layouts. medium is the default. On touch devices, small uses the body text size so iOS Safari doesn't zoom into the field on focus.

Combobox Field: Size

Open in playground

small

Example field

medium

Example field

import { ComboboxField, ComboboxItem } from '@luke-ui/react/combobox-field';
import { Comparison, ComparisonItem } from '#docs';

type Option = { id: string; label: string };

const options: Array<Option> = [
	{ id: 'one', label: 'Example option' },
	{ id: 'two', label: 'Another option' },
];

export default () => {
	return (
		<Comparison>
			<ComparisonItem label="small">
				<ComboboxField
					defaultItems={options}
					label="Example field"
					name="example"
					placeholder="Choose an option"
					size="small"
				>
					{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
				</ComboboxField>
			</ComparisonItem>
			<ComparisonItem label="medium">
				<ComboboxField
					defaultItems={options}
					label="Example field"
					name="example"
					placeholder="Choose an option"
					size="medium"
				>
					{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
				</ComboboxField>
			</ComparisonItem>
		</Comparison>
	);
};

Combobox Field: Size

Loading Combobox Field: Size example

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. With a reduced-motion preference, the tray fades in without sliding.

IDs and refs

id, className, and ref target the field's root element. Pass inputId to set the input's id, and inputRef to reach the input.

Accessibility

Provide a visible label where possible. When a nearby heading already names the field, omit label. Use aria-label or aria-labelledby instead.

Luke UI associates the label, description, and validation message with the input.

API

ComboboxFieldProps

ComboboxFieldProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type	Default
allowsCustomValue	boolean	—
Whether the ComboBox allows a non-item matching input value to be set.
allowsEmptyCollection	boolean \|⁠ undefined	`true`
Whether the menu can stay open when filtering leaves no items. Tray search and empty states need this so typing text that matches nothing does not dismiss the overlay.
defaultFilter	(textValue: string, inputValue: string) => boolean	—
The filter function used to determine if an option should be included in the combo box list. By default, a language-sensitive "contains" filter from `useFilter` is used.
defaultInputValue	string	—
The default value of the ComboBox input (uncontrolled).
defaultItems	Iterable<T>	—
The list of ComboBox items (uncontrolled).
description	ReactNode	—
Optional helper text shown below the control.
disabledKeys	Iterable<Key>	—
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
errorMessage	ReactNode	—
Validation message for a controlled error. A non-empty message marks the field invalid.
formValue	'text' \|⁠ 'key'	`'key'`
Whether the text or key of the selected item is submitted as part of an HTML form. When `allowsCustomValue` is `true`, this option does not apply and the text is always submitted.
inputId	string \|⁠ undefined	—
Element id for the input. The field generates one when omitted.
inputRef	Ref<HTMLInputElement>	—
Targets the persistent combobox input on desktop. On mobile it targets the tray search input only while the tray is open, so it is null when the tray is closed. Use `ref` for the root element.
inputValue	string	—
The value of the ComboBox input (controlled).
items	Iterable<T>	—
The list of ComboBox items (controlled).
label	Exclude<ReactNode, boolean \|⁠ null \|⁠ undefined>	—
Visible label. Pass non-empty, textual, non-interactive content. Place links and buttons outside it, and associate external label content with `aria-labelledby` instead.
listBoxProps	Omit<<<T>>, "children" \|⁠ "items" \|⁠ "loadMoreItem">	—
Props forwarded to the inner listbox.
loadingState		—
Async loading state used for built-in loading and empty states.
loadMoreItem	ReactNode	—
Optional content appended after the main collection, e.g. a load-more sentinel.
menuTrigger	'focus' \|⁠ 'input' \|⁠ 'manual'	`'focus'`
The interaction required to display the ComboBox menu.
menuWidth	Property.Width<number \|⁠ string> \|⁠ undefined	—
Width applied to the desktop popover menu. Mobile uses the tray instead.
necessityIndicator		—
Controls how the label identifies required or optional values. Inherits from `Form`, or uses `'required-asterisk'` when unset.
placeholder	string	—
Placeholder text shown in the input.
popoverProps	<, 'children'>	—
Props forwarded to the desktop popover. Mobile uses the tray instead.
shouldFocusWrap	boolean	—
Whether keyboard navigation is circular.
size		`'medium'`
Control size.

ComboboxItemProps

ComboboxItemProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type
download	boolean \|⁠ string
Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
href	Href
A URL to link to. See MDN.
hrefLang	string
Hints at the human language of the linked URL. SeeMDN.
ping	string
A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy	HTMLAttributeReferrerPolicy
How much of the referrer to send when following the link. See MDN.
rel	string
The relationship between the linked resource and the current page. See MDN.
size
target	HTMLAttributeAnchorTarget
The target window for the link. See MDN.
textValue	string
A string representation of the item's contents, used for features like typeahead.

ComboboxSectionProps

ComboboxSectionProps also accepts compatible DOM and ARIA attributes and event handlers for its rendered element.

Name	Type
dependencies	ReadonlyArray<any>
Values that should invalidate the item cache when using dynamic collections.
items	Iterable<T>
Item objects in the section.
title	ReactNode