||

Combobox

Documentation Index

Fetch the complete documentation index at: /llms.txt. Use this file to discover all available pages before exploring further.

An input combined with a list of predefined items to select.

doc
combobox-demo

Overview

Use a combobox when users choose one or more values from a list and search or filtering helps them find the right option.

Combobox is useful for large lists, people pickers, labels, projects, countries, commands, and multi-select workflows.

Anatomy

A combobox has a trigger or input, popup, list, items, and selection state. Single-selection comboboxes store one value. Multiple-selection comboboxes store a list of values.

Behavior

Use single selection when one value is allowed. Use multiple selection for tags, filters, permissions, or categories. Use clear buttons when users often reset the value.

Accessibility

Give the combobox a label and keep keyboard navigation intact. Users should be able to open the popup, move through options, select items, clear values, and close the popup without a mouse.

Installation

 
npx honestui@latest add combobox

Usage

Single Selection

import {
  Combobox,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
} from "@/components/ui/combobox"
const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Combobox items={items}>
  <ComboboxInput placeholder="Select an item..." />
  <ComboboxPopup>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem key={item.value} value={item}>{item.label}</ComboboxItem>}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>

Multiple Selection

import {
  Combobox,
  ComboboxChip,
  ComboboxChips,
  ComboboxEmpty,
  ComboboxInput,
  ComboboxItem,
  ComboboxList,
  ComboboxPopup,
  ComboboxValue,
} from "@/components/ui/combobox"
const items = [
  { value: "apple", label: "Apple" },
  { value: "banana", label: "Banana" },
  { value: "orange", label: "Orange" },
  { value: "grape", label: "Grape" },
]

<Combobox items={items} multiple>
  <ComboboxChips>
    <ComboboxValue>
      {(value: { value: string; label: string }[]) => (
        <>
          {value?.map((item) => (
            <ComboboxChip key={item.value} aria-label={item.value}>
              {item.label}
            </ComboboxChip>
          ))}
          <ComboboxInput
            placeholder={value.length > 0 ? undefined : "Select a Select an item..."}
            aria-label="Select an item"
          />
        </>
      )}
    </ComboboxValue>
  </ComboboxChips>
  <ComboboxPopup>
    <ComboboxEmpty>No results found.</ComboboxEmpty>
    <ComboboxList>
      {(item) => <ComboboxItem value={item}>{item.label}</ComboboxItem>}
    </ComboboxList>
  </ComboboxPopup>
</Combobox>

API Reference

The ComboboxInput component extends the original Base UI component with a few extra props:

PropTypeDefaultDescription
size"sm" | "default" | "lg""default"The size variant of the input field.
showTriggerbooleantrueWhether to display a trigger button (chevron icon) on the right side of the input.
showClearbooleanfalseWhether to display a clear button (X icon) on the right side of the input when there is a value.

Examples

Our examples cover disabled, sized, labeled, grouped, single-selection, multiple-selection, input-in-popup, and form-connected comboboxes.

Disabled

combobox-disabled

Small Size

combobox-sm

Large Size

combobox-lg

With Label

combobox-with-label

Auto Highlight

Automatically highlight the first matching option.

combobox-autohighlight

With Clear Button

combobox-with-clear

With Groups

combobox-grouped

With Multiple Selection

combobox-multiple

With Input Inside Popup

combobox-with-inner-input

Form Integration

combobox-form

Form Integration - Multiple

combobox-multiple-form