Combobox primitives

Use these primitives when ComboboxField does not fit your layout or loading UI. They expose the control, popover, listbox, and option parts used by the composed field. Application code should usually use ComboboxField.

import {
	ComboboxControl,
	ComboboxItem,
	ComboboxListBox,
	ComboboxPopover,
	ComboboxRoot,
	ComboboxTextInput,
	ComboboxTrigger,
} from '@luke-ui/react/combobox-field/primitive';

Anatomy

ComboboxRoot owns the searchable single-select state. Put the control and popover inside it. Put the text input and trigger in ComboboxControl, then put the listbox and its items in ComboboxPopover.

<ComboboxRoot defaultItems={countries} aria-label="Country">
	<ComboboxControl>
		<ComboboxTextInput />
		<ComboboxTrigger aria-label="Toggle options" />
	</ComboboxControl>
	<ComboboxPopover>
		<ComboboxListBox>{(item) => <ComboboxItem>{item.label}</ComboboxItem>}</ComboboxListBox>
	</ComboboxPopover>
</ComboboxRoot>

Control and options

ComboboxTextInput opens the menu when clicked and supplies the editable combobox input. ComboboxTrigger toggles the option menu. ComboboxClearButton renders only when the root has a selection and clears both the selection and input value.

Use ComboboxItem for options. It adds a checkmark for the selected option. ComboboxSection groups related options and can render a heading. ComboboxListBox accepts static children or a render function with items. Its loadMoreItem slot appends content after the main collection.

Size

Set size on ComboboxRoot to give the control and option primitives a shared size. Individual ComboboxControl, ComboboxTextInput, ComboboxClearButton, ComboboxTrigger, ComboboxItem, and ComboboxLoadMoreItem components can override that size when needed.

Loading and empty results

Use ComboboxLoadMoreItem as the listbox's load-more sentinel. Use ComboboxEmptyState for custom empty content, including a loading message or spinner. ComboboxField supplies common loading and empty-state handling when its built-in composition is enough.

Popover and accessibility

ComboboxPopover preserves the active Luke UI theme identity and explicit colour mode when it portals the listbox. Below the small breakpoint, it becomes a full-width bottom tray instead of a positioned popover.

Give ComboboxRoot an accessible name with aria-label or a connected label. Keep the root/control/input/listbox structure so React Aria's combobox semantics and keyboard behaviour remain intact.