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
Selectwhen the list is short and needs no filter. - Prefer
MultiSelectwhen the user picks several values, shown as tags. - Prefer
Commandwhen the list runs actions or goes to pages, in a palette. - Prefer
Querywhen the field filters a list with free text andkey:valuequalifiers.
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:
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:
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:
Combobox.Item
Renders a combobox item inside a Combobox.Content component.
All props from ariakit ComboboxItem, plus:
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:
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:
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:
Combobox.Separator
Renders a separator between Combobox.Items or Combobox.Groups.
All props from Separator.