Primitives

Combobox primitives

Lower-level parts for composing a searchable single-select combobox.

React Aria SourceView as Markdown Edit on GitHub

Use these primitives when ComboboxField does not fit your layout or loading UI. They expose the control, popover, listbox, and option parts used by ComboboxField.

Combobox primitives: Basic

Open in playground

import { Icon } from '@luke-ui/react/icon';
import {
	ComboboxControl,
	ComboboxInput,
	ComboboxItem,
	ComboboxListBox,
	ComboboxPopover,
	ComboboxRoot,
	ComboboxTrigger,
} from '@luke-ui/react/primitives/combobox';

export default () => {
	return (
		<ComboboxRoot aria-label="Country">
			<ComboboxControl>
				<ComboboxInput />
				<ComboboxTrigger aria-label="Toggle options">
					<Icon name="chevronDown" />
				</ComboboxTrigger>
			</ComboboxControl>
			<ComboboxPopover>
				<ComboboxListBox>
					<ComboboxItem id="au">Australia</ComboboxItem>
					<ComboboxItem id="nz">New Zealand</ComboboxItem>
				</ComboboxListBox>
			</ComboboxPopover>
		</ComboboxRoot>
	);
};

Combobox primitives: Basic

Loading Combobox primitives: Basic example

Anatomy

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

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

id and ref on ComboboxRoot target the root element. Pass inputId to set the input's id.

Control and options

ComboboxInput opens the menu when someone clicks it 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, ComboboxInput, ComboboxClearButton, ComboboxTrigger, ComboboxItem, and ComboboxLoadMoreItem components can override that size when necessary. ComboboxControl sizes a nested Icon the same way TextInputControl does at the same control size.

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.

Tray presentation

ComboboxTray shows options in a full-screen tray. Pair it with ComboboxTrayTrigger to show the current selection and open the tray. The tray dialog takes its accessible name from the root: a connected label, or aria-label / aria-labelledby on ComboboxRoot.

Combobox primitives: Tray

Open in playground

import { Button } from '@luke-ui/react/button';
import { Cluster } from '@luke-ui/react/cluster';
import { Icon } from '@luke-ui/react/icon';
import {
	ComboboxClearButton,
	ComboboxControl,
	ComboboxInput,
	ComboboxItem,
	ComboboxListBox,
	ComboboxRoot,
	ComboboxTray,
	ComboboxTrayTrigger,
} from '@luke-ui/react/primitives/combobox';
import { Field } from '@luke-ui/react/primitives/field';
import { Stack } from '@luke-ui/react/stack';
import type { SubmitEvent } from 'react';

const countries = [
	{ id: 'australia', label: 'Australia' },
	{ id: 'new-zealand', label: 'New Zealand' },
];

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

export default () => {
	return (
		<form onSubmit={handleSubmit}>
			<Stack gap="space.16">
				<ComboboxRoot defaultItems={countries} isRequired name="country">
					<Field label="Country">
						<ComboboxControl>
							<ComboboxTrayTrigger placeholder="Select a country...">
								<Icon name="chevronDown" />
							</ComboboxTrayTrigger>
						</ComboboxControl>
						<ComboboxTray>
							<ComboboxControl>
								<ComboboxInput placeholder="Select a country..." />
								<ComboboxClearButton aria-label="Clear search">
									<Icon name="close" />
								</ComboboxClearButton>
							</ComboboxControl>
							<ComboboxListBox<{ id: string; label: string }>>
								{(item) => <ComboboxItem>{item.label}</ComboboxItem>}
							</ComboboxListBox>
						</ComboboxTray>
					</Field>
				</ComboboxRoot>
				<Cluster>
					<Button type="submit">Create account</Button>
				</Cluster>
			</Stack>
		</form>
	);
};

Combobox primitives: Tray

Loading Combobox primitives: Tray example

Inside the tray, ComboboxInput is the search field. ComboboxClearButton clears the search and the selection. ComboboxField chooses the tray or the popover for you.

ComboboxRoot defaults allowsEmptyCollection to true, so typing a filter that matches no options keeps the tray open for empty states and custom values.

While the tray is closed, ComboboxTrayTrigger keeps constraint validation and form submission working. Pass isRequired, validationBehavior, isDisabled, isReadOnly, form, and allowsCustomValue on the root.

Set isRequired so a field blocks submit until someone chooses a value, or enters custom text when allowsCustomValue is set. Set validationBehavior="aria" on the root to report validation through ARIA instead of the constraint API.

The field submits under the root's name. By default that value is the selected key. Set formValue="text", or set allowsCustomValue, to submit text instead — including a selected option's label, or custom text that has no key. The search field does not submit, so the field sends one value whether the tray is open or closed.

A read-only field still submits. So does a field with validationBehavior="aria". A disabled field submits nothing in text mode. In key mode a disabled field still submits the selected key.

ComboboxPopover preserves the active Luke UI theme identity and explicit colour mode when it portals the listbox. It portals a desktop-style positioned popover and never becomes a tray. Use ComboboxTray for the tray presentation.

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.

API

ComboboxRootProps

ComboboxRootProps 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).
disabledKeys	Iterable<Key>	—
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
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 combobox input. The root generates one when omitted.
inputValue	string	—
The value of the ComboBox input (controlled).
items	Iterable<T>	—
The list of ComboBox items (controlled).
menuTrigger	'focus' \|⁠ 'input' \|⁠ 'manual'	`'focus'`
The interaction required to display the ComboBox menu.
shouldFocusWrap	boolean	—
Whether keyboard navigation is circular.
size		`'medium'`
Control size.

ComboboxControlProps

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

Name	Type	Default
size		—

ComboboxInputProps

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

Name	Type
placeholder	string
Temporary text that occupies the text input when it is empty. See MDN.
size

ComboboxClearButtonProps

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

Name	Type	Default
isPending	boolean	—
Whether the button is in a pending state. This disables press and hover events while retaining focusability, and announces the pending state to screen readers.
size		—

ComboboxTriggerProps

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

Name	Type	Default
isPending	boolean	—
Whether the button is in a pending state. This disables press and hover events while retaining focusability, and announces the pending state to screen readers.
size		—

ComboboxPopoverProps

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

Name	Type	Default
arrowBoundaryOffset	number	`0`
The minimum distance the arrow's edge should be from the edge of the overlay element.
arrowRef	RefObject<Element \|⁠ null>	—
A ref for the popover arrow element.
boundaryElement	Element	`document.body`
Element that that serves as the positioning boundary.
containerPadding	number	`12`
The placement padding that should be applied between the element and its surrounding container.
crossOffset	number	`0`
The additional offset applied along the cross axis between the element and its anchor element.
defaultOpen	boolean	—
Whether the overlay is open by default (uncontrolled).
getTargetRect	(target: Element) => DOMRect \|⁠ null \|⁠ undefined	`target.getBoundingClientRect()`
Overrides the target element's bounding rectangle. Useful for positioning relative to a specific point such as the mouse cursor (e.g. context menus) or text selection. Parameters target The target element.
isEntering	boolean	—
Whether the popover is currently performing an entry animation.
isExiting	boolean	—
Whether the popover is currently performing an exit animation.
isKeyboardDismissDisabled	boolean	`false`
Whether pressing the escape key to close the popover should be disabled. Most popovers should not use this option. When set to true, an alternative way to close the popover with a keyboard must be provided.
isNonModal	boolean	—
Whether the popover is non-modal, i.e. elements outside the popover may be interacted with by assistive technologies. Most popovers should not use this option as it may negatively impact the screen reader experience. Only use with components such as combobox, which are designed to handle this situation carefully.
isOpen	boolean	—
Whether the overlay is open by default (controlled).
maxHeight	number	—
The maxHeight specified for the overlay element. By default, it will take all space up to the current viewport height.
offset	number	`8`
The additional offset applied along the main axis between the element and its anchor element.
placement	Placement	`'bottom'`
The placement of the element with respect to its anchor element.
scrollRef	RefObject<Element \|⁠ null>	`overlayRef`
A ref for the scrollable region within the overlay.
shouldCloseOnInteractOutside	(element: Element) => boolean	—
When user interacts with the argument element outside of the popover ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the popover. By default, onClose will always be called on interaction outside the popover ref.
shouldFlip	boolean	`true`
Whether the element should flip its orientation (e.g. top to bottom or left to right) when there is insufficient room for it to render completely.
shouldSkipAnimation	boolean	—
Whether the popover should appear and disappear without an entry or exit animation. This is used by components such as PreviewTrigger to skip animations when quickly swapping between overlays.
shouldUpdatePosition	boolean	`true`
Whether the overlay should update its position automatically.
trigger	string	—
The name of the component that triggered the popover. This is reflected on the element as the `data-trigger` attribute, and can be used to provide specific styles for the popover depending on which element triggered it.
triggerRef	RefObject<Element \|⁠ null>	—
The ref for the element which the popover positions itself with respect to. When used within a trigger component such as DialogTrigger, MenuTrigger, Select, etc., this is set automatically. It is only required when used standalone.

ComboboxTrayTriggerProps

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

Name	Type	Default
isPending	boolean	—
Whether the button is in a pending state. This disables press and hover events while retaining focusability, and announces the pending state to screen readers.
placeholder	string	—
Text shown while nothing is selected.
size		—

ComboboxTrayProps

Name	Type

ComboboxListBoxProps

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

Name	Type	Default
defaultSelectedKeys	'all' \|⁠ Iterable<Key>	—
The initial selected keys in the collection (uncontrolled).
dependencies	ReadonlyArray<unknown>	—
Values that should invalidate the dynamic item cache.
disabledKeys	Iterable<Key>	—
The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
disallowEmptySelection	boolean	—
Whether the collection allows empty selection.
dragAndDropHooks	DragAndDropHooks<NoInfer<T>>	—
The drag and drop hooks returned by `useDragAndDrop` used to enable drag and drop behavior for the ListBox.
escapeKeyBehavior	'clearSelection' \|⁠ 'none'	`'clearSelection'`
Whether pressing the escape key should clear selection in the listbox or not. Most experiences should not modify this option as it eliminates a keyboard user's ability to easily clear selection. Only use if the escape key is being handled externally or should not trigger selection clearing contextually.
items	Iterable<T>	—
Dynamic items rendered by the `children` render prop.
layout	'stack' \|⁠ 'grid'	`'stack'`
Whether the items are arranged in a stack or grid.
loadMoreItem	ReactNode	—
Optional content appended after the main collection, e.g. a load-more sentinel.
orientation	Orientation	`'vertical'`
The primary orientation of the items. Usually this is the direction that the collection scrolls.
renderEmptyState	(props: ListBoxRenderProps) => ReactNode	—
Provides content to display when there are no items in the list.
selectedKeys	'all' \|⁠ Iterable<Key>	—
The currently selected keys in the collection (controlled).
selectionBehavior	SelectionBehavior	`'toggle'`
How multiple selection should behave in the collection.
selectionMode	SelectionMode	—
The type of selection that is allowed in the collection.
shouldFocusOnHover	boolean	—
Whether options should be focused when the user hovers over them.
shouldFocusWrap	boolean	—
Whether focus should wrap around when the end/start is reached.
shouldSelectOnPressUp	boolean	—
Whether selection should occur on press up instead of press down.

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.

ComboboxLoadMoreItemProps

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

Name	Type	Default
isLoading	boolean	—
Whether or not the loading spinner should be rendered or not.
scrollOffset	number	`1`
The amount of offset from the bottom of your scrollable region that should trigger load more. Uses a percentage value relative to the scroll body's client height. Load more is then triggered when your current scroll position's distance from the bottom of the currently loaded list of items is less than or equal to the provided value. (e.g. 1 = 100% of the scroll region's height).
size		—

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

ComboboxEmptyStateProps

Name	Type