Skip to main content

Combobox

A text input with autocomplete: the user types to filter a list of suggested values and picks one, with full keyboard support. Wrap Combobox.Input in Field.Control to connect it to the label, description, and errors of a form field.

When to use

  • Pick one value from a long list, with a text field that filters the options as the user types.
  • Search async or server-side data for one value.
  • Prefer Select when the list is short and needs no filter.
  • Prefer MultiSelect when the user picks several values, shown as tags.
  • Prefer Command when the list runs actions or goes to pages, in a palette.
  • Prefer Query when the field filters a list with free text and key:value qualifiers.

Without helper text

Use a Field.Item with only a Field.Label when the input needs no helper or error text. The label still gives the input its accessible name. This example also shows a disabled item, an item icon, and a separator.

Layering and z-index

Combobox.Content renders in place at Tailwind z-50, Mantle's float tier. It does not portal, so the dialog primitive's Escape guard can see it. Inside an overlay it paints with the overlay's content. Outside one, an open overlay (z-60) covers it.

Combobox does not render a backdrop. Modal layers such as Dialog, Sheet, and AlertDialog do render backdrops, so stacking those layers compounds the dim and blur effect on the layers underneath.

Examples

With TanStack Form

Use @tanstack/react-form with zod to keep the combobox input controlled. Wrap Combobox.Input in Field.Control so label, name, and validation ARIA are applied to the focusable input.

Composition

Compose the parts of a Combobox together to build your own:

Combobox.Root├── Combobox.Input└── Combobox.Content    ├── Combobox.Group    │   ├── Combobox.GroupLabel    │   └── Combobox.Item    │       └── Combobox.ItemValue    └── Combobox.Separator

Polymorphism

Combobox.Content, Combobox.Item, Combobox.Group, Combobox.GroupLabel, and Combobox.ItemValue support asChild to render as a different element or your own component while keeping the combobox behavior and styling.

Accessibility

Combobox follows the WAI-ARIA Combobox Pattern and builds on the ariakit Combobox. Inside a field, Field.Control puts the generated id, name, aria-describedby, aria-errormessage, and aria-invalid on the focusable input.

API Reference

The Combobox components are built on top of ariakit Combobox.

Combobox.Root

The outermost part of a combobox. It owns the ariakit store that holds the query text, the open state, and the selection.

Combobox.Content renders in place at Tailwind z-50, Mantle's float tier. It does not portal, so the dialog primitive's Escape guard can see it. Inside an overlay it paints with the overlay's content. Outside one, an open overlay (z-60) covers it.

All props from ariakit ComboboxProvider.

Combobox.Input

Renders a combobox input element for filtering a list of items.

All props from ariakit Combobox, plus:

PropTypeDefaultDescription
autoComplete?string"list"The autocomplete behavior of the input.
autoSelect?boolean | "always""always"How the first item is automatically selected.
validation?"error" | "success" | "warning" | false | (() => "error" | "success" | "warning" | false)Validation state that changes the border and outline.

Combobox.Content

Renders a popover that contains combobox content, e.g. items, groups, and separators.

Combobox.Content renders in place at Tailwind z-50, Mantle's float tier. It does not portal, so the dialog primitive's Escape guard can see it. Inside an overlay it paints with the overlay's content. Outside one, an open overlay (z-60) covers it.

All props from ariakit ComboboxPopover, plus:

PropTypeDefaultDescription
asChild?booleanfalseCompose onto an alternative element type or your own React component.
sameWidth?booleantrueWhether the popover should be the same width as the input.
unmountOnHide?booleantrueWhether the popover should unmount when hidden.

Combobox.Item

Renders a combobox item inside a Combobox.Content component.

All props from ariakit ComboboxItem, plus:

PropTypeDefaultDescription
asChild?booleanfalseCompose onto an alternative element type or your own React component.
focusOnHover?booleantrueWhether the item should receive focus on hover.

Combobox.ItemValue

Highlights the match between the current Combobox.Input value and parent Combobox.Item value. Should only be used as a child of Combobox.Item.

All props from ariakit ComboboxItemValue, plus:

PropTypeDefaultDescription
asChild?booleanfalseCompose onto an alternative element type or your own React component.

Combobox.Group

Renders a group for Combobox.Item elements. Optionally, compose a Combobox.GroupLabel as a child to label the group.

All props from ariakit ComboboxGroup, plus:

PropTypeDefaultDescription
asChild?booleanfalseCompose onto an alternative element type or your own React component.

Combobox.GroupLabel

Renders a label in a combobox group. Should be wrapped with Combobox.Group so the aria-labelledby is correctly set on the group element.

All props from ariakit ComboboxGroupLabel, plus:

PropTypeDefaultDescription
asChild?booleanfalseCompose onto an alternative element type or your own React component.

Combobox.Separator

Renders a separator between Combobox.Items or Combobox.Groups.

All props from Separator.