Combobox

Filterable select with single and multi-select modes, grouped options, chips, loading and empty states, and all Field variants.

Installation

pnpm add @tessinaui/ui

Usage

import {
  ComboboxRoot,
  ComboboxInputGroup,
  ComboboxInput,
  ComboboxTrigger,
  ComboboxClear,
  ComboboxLeadingIcon,
  ComboboxPopup,
  ComboboxList,
  ComboboxItem,
  ComboboxEmpty,
  ComboboxFilterTabs,
  ComboboxFilterTab,
} from "@tessinaui/ui";

{/* Single select */}
<ComboboxRoot label="Fruit" value={value} onValueChange={setValue}>
  <ComboboxInputGroup>
    <ComboboxInput placeholder="Search…" />
    <ComboboxClear />
    <ComboboxTrigger />
  </ComboboxInputGroup>
  <ComboboxPopup>
    <ComboboxList>
      <ComboboxItem value="apple">Apple</ComboboxItem>
      <ComboboxItem value="banana">Banana</ComboboxItem>
      <ComboboxEmpty />
    </ComboboxList>
  </ComboboxPopup>
</ComboboxRoot>

{/* Multi-select with chips */}
<ComboboxRoot multiple label="Fruits" value={values} onValueChange={setValues}>
  <ComboboxInputGroup>
    <ComboboxChips>
      {values.map((v) => (
        <ComboboxChip key={v} value={v}>
          {v}
          <ComboboxChipRemove />
        </ComboboxChip>
      ))}
      <ComboboxInput placeholder="Search…" />
    </ComboboxChips>
    <ComboboxClear />
    <ComboboxTrigger />
  </ComboboxInputGroup>
  <ComboboxPopup>
    <ComboboxList>
      <ComboboxItem value="apple">Apple</ComboboxItem>
      <ComboboxItem value="banana">Banana</ComboboxItem>
      <ComboboxEmpty />
    </ComboboxList>
  </ComboboxPopup>
</ComboboxRoot>

Playground

Preview

Size

Intent

Rounded

Width

Label position

Direction

Select a fruit

API Reference

ComboboxRoot props

Prop	Type	Default	Description
`size`	`"xs" \| "sm" \| "md" \| "lg" \| "xl"`	`"md"`	Input height and text size
`intent`	`"none" \| "error" \| "warning" \| "success" \| "info"`	`"none"`	Border and focus-ring color
`rounded`	`"none" \| "sm" \| "md" \| "lg" \| "full"`	`"full"`	Border radius
`labelPosition`	`"outside-top" \| "inside" \| "outside-left"`	`"outside-top"`	Label layout position
`label`	`string`	—	Label text
`required`	`boolean`	—	Adds asterisk to label and `aria-required`
`infoText`	`string`	—	Inline info hint shown next to label
`supportingText`	`string`	—	Helper/error text below the input
`multiple`	`boolean`	`false`	Enables multi-select with chips
`value`	`string \| string[]`	—	Controlled selected value(s)
`defaultValue`	`string \| string[]`	—	Uncontrolled initial value(s)
`onValueChange`	`(value) => void`	—	Called when selection changes
`disabled`	`boolean`	—	Disables the whole combobox
`autoHighlight`	`boolean`	`false`	Auto-highlights first matching item while filtering
`dir`	`"ltr" \| "rtl"`	`"ltr"`	Text direction
`wrapperClassName`	`string`	—	Class applied to the outermost wrapper div

ComboboxItem props

Prop	Type	Description
`value`	`any`	The value this item represents
`disabled`	`boolean`	Prevents selection
`leadingIcon`	`ReactNode`	Icon shown before the label
`leadingAvatar`	`ReactNode`	Avatar shown before the label
`description`	`string`	Secondary text shown below the label

ComboboxLeadingIcon props

Prop	Type	Description
`onClick`	`() => void`	Makes the icon interactive (pointer cursor + hover); omit for decorative

Renders a size-responsive icon slot at the very start of ComboboxInputGroup, before the input or chips. Accepts any ReactNode as children — pass a Lucide icon, an Avatar, or any element.

ComboboxFilterTabs props

Prop	Type	Default	Description
`value`	`string`	—	The currently active tab value
`onValueChange`	`(v: string) => void`	—	Called when a tab is clicked

Renders a horizontal row of filter tabs inside ComboboxPopup, above the list. Tabs are purely visual — wire onValueChange to filter the items array yourself.

ComboboxFilterTab props

Prop	Type	Description
`value`	`string`	The value this tab represents
`count`	`number`	Optional count badge shown after the label

Combobox

On this page