Combobox

Pass options as { value, label, disabled? }. Filtering runs by label while the Zag.js machine manages focus, keyboard navigation, and selection.

import { Combobox } from '@manti-ui/react';

const spices = [
  { value: 'sumac', label: 'Sumac' },
  { value: 'paprika', label: 'Paprika' },
  { value: 'cumin', label: 'Cumin' },
  { value: 'mint', label: 'Dried mint' },
  { value: 'pepper', label: 'Black pepper' },
  { value: 'chili', label: 'Chili flakes' },
  { value: 'coriander', label: 'Coriander' },
];

export default function ComboboxBasic() {
  return (
    <div className="w-full max-w-[calc(var(--manti-space-16)*5)]">
      <Combobox items={spices} label="Spice" placeholder="Search spices…" />
    </div>
  );
}

Appearance

Use variant="fill" for a neutral filled control. size uses the shared size scale: the portalled list follows the control, so a sm Combobox filters into sm rows.

Default

Filled

Small

Medium

Large

Multiple selection

Set multiple to collect several values.

Spices

SumacDried mint

API

Prop	Type	Default	Description
`items`	`ComboboxItem[]`	—	The full option set; filtered client-side as the user types. Each item is { value, label, disabled? }.
`label`	`ReactNode`	—	Optional field label.
`placeholder`	`string`	`'Search…'`	Input placeholder text.
`variant`	`'default' \| 'fill'`	`'default'`	Visual treatment for the control.
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Control size.
`maxVisibleItems`	`number`	`200`	How many matching rows the listbox renders at once. Typing filters the whole item set; a line under the rows says how many matches are still hidden.
`multiple`	`boolean`	—	Allow selecting more than one option.
`value`	`string[]`	—	Controlled selected values.
`defaultValue`	`string[]`	—	Initial selected values for uncontrolled usage.
`onValueChange`	`(value: string[]) => void`	—	Called whenever the selection changes.
`placement`	`Placement`	`'bottom-start'`	Placement of the listbox relative to the control.
`disabled`	`boolean`	—	Disable the control.
`invalid`	`boolean`	—	Mark the field as invalid.
`required`	`boolean`	—	Mark the field as required.
`name`	`string`	—	Form field name.

Styling

Anatomy

Part	Selector	Description
`root`	`[data-scope="combobox"][data-part="root"]`	The field wrapper; carries data-size and data-variant.
`label`	`[data-scope="combobox"][data-part="label"]`	The field label.
`control`	`[data-scope="combobox"][data-part="control"]`	Wraps the input and toggle button.
`input`	`[data-scope="combobox"][data-part="input"]`	The typeahead text input.
`trigger`	`[data-scope="combobox"][data-part="trigger"]`	The button that toggles the listbox open.
`positioner`	`[data-scope="combobox"][data-part="positioner"]`	Positions the floating listbox.
`content`	`[data-scope="combobox"][data-part="content"]`	The translucent listbox panel.
`item`	`[data-scope="combobox"][data-part="item"]`	A selectable option.
`item-indicator`	`[data-scope="combobox"][data-part="item-indicator"]`	The check mark shown on selected items.
`overflow-hint`	`[data-scope="combobox"][data-part="overflow-hint"]`	The line under the rows when more matches exist than maxVisibleItems.

Tokens

Token	Controls
`--manti-combobox-height`	height
`--manti-combobox-padding-x`	padding x
`--manti-combobox-icon-size`	icon size
`--manti-combobox-content-max-height`	content max height
`--manti-combobox-content-padding`	content padding
`--manti-combobox-content-gap`	content gap
`--manti-combobox-item-padding-y`	item padding y
`--manti-combobox-item-padding-x`	item padding x
`--manti-combobox-item-gap`	item gap
`--manti-combobox-item-radius`	item radius
`--manti-combobox-item-font-size`	item font size

Last updated 13 September 2026