# Combobox primitives (/components/primitives/combobox)
Use these primitives when [`ComboboxField`](/components/forms/combobox-field) does not fit your
layout or loading UI. They expose the control, popover, listbox, and option parts used by
`ComboboxField`. Start with `ComboboxField` when it fits.
apps/docs/src/examples/combobox-primitive/basic.tsx
```tsx
import { Icon } from '@luke-ui/react/icon';
import {
ComboboxInput,
ComboboxInputGroup,
ComboboxItem,
ComboboxListBox,
ComboboxPopover,
ComboboxRoot,
ComboboxTrigger,
} from '@luke-ui/react/primitives/combobox';
export default () => {
return (
Australia
New Zealand
);
};
```
## Anatomy [#anatomy]
`ComboboxRoot` owns the searchable single-select state. Put the control and popover inside it. Put
the text input and trigger in `ComboboxInputGroup`. Put the listbox and its items in
`ComboboxPopover`.
```tsx
>
{(item) => {item.label}}
```
## Control and options [#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 [#size]
Set `size` on `ComboboxRoot` to give the control and option primitives a shared size. Individual
`ComboboxInputGroup`, `ComboboxInput`, `ComboboxClearButton`, `ComboboxTrigger`, `ComboboxItem`, and
`ComboboxLoadMoreItem` components can override that size when necessary. `ComboboxInputGroup` sizes
a nested `Icon` the same way `InputGroup` does at the same control size.
## Loading and empty results [#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.
## Tray presentation [#tray-presentation]
`ComboboxTray` shows options in a full-screen tray. Pair it with `ComboboxTrayTrigger` to show the
current selection and open the tray.
apps/docs/src/examples/combobox-primitive/tray.tsx
```tsx
import { Box } from '@luke-ui/react/box';
import { Button } from '@luke-ui/react/button';
import { Icon } from '@luke-ui/react/icon';
import {
ComboboxClearButton,
ComboboxInput,
ComboboxInputGroup,
ComboboxItem,
ComboboxListBox,
ComboboxRoot,
ComboboxTray,
ComboboxTrayTrigger,
} from '@luke-ui/react/primitives/combobox';
import { Field } from '@luke-ui/react/primitives/field';
import type { SubmitEvent } from 'react';
const countries = [
{ id: 'australia', label: 'Australia' },
{ id: 'new-zealand', label: 'New Zealand' },
];
export default () => {
function handleSubmit(event: SubmitEvent) {
event.preventDefault();
}
return (
);
};
```
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.
## Popover and accessibility [#popover-and-accessibility]
`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 [#api]
### ComboboxRootProps [#comboboxrootprops]
### ComboboxInputGroupProps [#comboboxinputgroupprops]
### ComboboxInputProps [#comboboxinputprops]
### ComboboxClearButtonProps [#comboboxclearbuttonprops]
### ComboboxTriggerProps [#comboboxtriggerprops]
### ComboboxPopoverProps [#comboboxpopoverprops]
### ComboboxTrayTriggerProps [#comboboxtraytriggerprops]
### ComboboxTrayProps [#comboboxtrayprops]
### ComboboxListBoxProps [#comboboxlistboxprops]
### ComboboxItemProps [#comboboxitemprops]
### ComboboxLoadMoreItemProps [#comboboxloadmoreitemprops]
### ComboboxSectionProps [#comboboxsectionprops]
### ComboboxEmptyStateProps [#comboboxemptystateprops]