Combobox

Use Combobox when the user searches, highlights, and selects structured options. Use Popover only for generic floating panels.

GitHub

Anatomy#

import {
  Combobox,
  ComboboxClear,
  ComboboxContent,
  ComboboxControl,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxItemIndicator,
  ComboboxList,
  ComboboxTriggerIndicator,
  Field,
  FieldLabel,
} from "raft-ui";

<Combobox>
  <Field>
    <FieldLabel />
    <ComboboxControl>
      <ComboboxInput />
      <ComboboxClear />
      <ComboboxTriggerIndicator />
    </ComboboxControl>
  </Field>
  <ComboboxContent>
    <ComboboxList>
      <ComboboxItem value="option">
        <ComboboxItemIndicator />
      </ComboboxItem>
    </ComboboxList>
    <ComboboxEmpty />
  </ComboboxContent>
</Combobox>

For async or server-provided results, use filter={null} to avoid re-filtering them while keeping inputValue controlled. ComboboxControlowns the searchable field surface; compose its icons, input, clear, and trigger indicator as children.

Model

Button trigger#

Load options#

Async select#

Custom trigger#

API#WIP

Combobox#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Root.Props	—	Owns selected value, input value, filtering, highlighted item, Escape, and Enter selection.

ComboboxLabel#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Label.Props	—	Accessible label for the combobox.

ComboboxControl#

Prop	Type	Default	Description
`...props`	Base UI Combobox.InputGroup.Props	—	Input-first control surface. Use it when the visible combobox trigger should be searchable; plain SVG children get the component's default icon size.

ComboboxTrigger#

Prop	Type	Default	Description
`render`	ReactElement \| (props, state) => ReactElement	—	Replaces the trigger element entirely. When provided, the default Button and its recipe styles are skipped; pass event and aria props to your own element.
`...props`	Base UI Combobox.Trigger.Props	—	Default trigger renders an outline md Button for picker-style filters where the search input lives inside the popup.

ComboboxValue#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Value.Props	—	Displayed value slot inside the trigger.

ComboboxTriggerCount#

Prop	Type	Default	Description
`...props`	StyledProps<ComponentPropsWithRef<"span">>	—	Count badge shown next to the trigger value.

ComboboxTriggerIndicator#

Prop	Type	Default	Description
`...props`	StyledProps<ComponentPropsWithRef<"span">>	—	Chevron or custom indicator inside the trigger.

ComboboxInput#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Input.Props	—	Search input. Supports password-manager suppression for compact filter panels.

ComboboxInputGroup#

Prop	Type	Default	Description
`...props`	Base UI Combobox.InputGroup.Props	—	Layout wrapper grouping the input with trigger actions.

ComboboxClear#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Clear.Props	—	Clears the current input and selected value through the primitive.

ComboboxContent#

Prop	Type	Default	Description
`...props`	Base UI Popup + Positioner props	—	Portaled popup shell. Defaults to side=bottom, align=start, sideOffset=4, and local collision props.

ComboboxPortal#

Prop	Type	Default	Description
`container`	HTMLElement \| RefObject \| null	—	Custom portal container for framed previews or contained overlays.
`...props`	Base UI Combobox.Portal.Props	—	Portals the popup to the body or a custom container.

ComboboxHeader#

Prop	Type	Default	Description
`...props`	div props	—	Header row for picker titles and trailing actions.

ComboboxSeparator#

Prop	Type	Default	Description
`...props`	div props	—	Horizontal divider between composed combobox regions.

Prop	Type	Default	Description
`...props`	div props	—	Unpositioned popup shell for advanced static rendering. Prefer ComboboxContent for trigger-anchored pickers.

ComboboxList#

Prop	Type	Default	Description
`...props`	Base UI Combobox.List.Props	—	Renders filtered items, usually through the list render function.

ComboboxEmpty#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Empty.Props	—	Empty-state message shown when no options match.

ComboboxGroup#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Group.Props	—	Group container for related options.

ComboboxGroupLabel#

Prop	Type	Default	Description
`...props`	Base UI Combobox.GroupLabel.Props	—	Group heading inside ComboboxGroup.

ComboboxRow#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Row.Props	—	Row layout for composite options.

ComboboxItem#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Item.Props	—	Selectable option row. Selection/highlight state is exposed through data attributes.

ComboboxItemIndicator#

Prop	Type	Default	Description
`...props`	Base UI Combobox.ItemIndicator.Props	—	Selected-state indicator for single and multiple selection.

ComboboxCollection#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Collection.Props	—	Collects items for keyboard navigation and filtering.

ComboboxChips#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Chips.Props	—	Wrap container for selected-value chips.

ComboboxChip#

Prop	Type	Default	Description
`...props`	Base UI Combobox.Chip.Props	—	Single selected-value chip.

ComboboxChipRemove#

Prop	Type	Default	Description
`...props`	Base UI Combobox.ChipRemove.Props	—	Dismiss control inside a selected-value chip.