Combobox

An input that filters a list of options as you type. Built on Base UI's combobox primitive, so filtering, keyboard navigation, and ARIA wiring come for free. Looking for a ready-made province & city picker? See City Selector.

Last updated August 6, 2026

Overview

Examples

Multiple selection

Next.js

Groups

Clear button

Disabled

Installation

$ npx shadcn@latest add @persianlabsui/combobox

Usage

import {
  Combobox,
  ComboboxContent,
  ComboboxEmpty,
  ComboboxIcon,
  ComboboxInput,
  ComboboxInputGroup,
  ComboboxItem,
  ComboboxList,
} from "@/components/ui/combobox"
 
const frameworks = ["Next.js", "SvelteKit", "Nuxt.js", "Remix", "Astro"]
 
export function Example() {
  return (
    <Combobox items={frameworks}>
      <ComboboxInputGroup>
        <ComboboxInput placeholder="Select a framework" />
        <ComboboxIcon />
      </ComboboxInputGroup>
      <ComboboxContent>
        <ComboboxEmpty>No frameworks found.</ComboboxEmpty>
        <ComboboxList>
          {(item) => <ComboboxItem key={item} value={item}>{item}</ComboboxItem>}
        </ComboboxList>
      </ComboboxContent>
    </Combobox>
  )
}

API Reference

Combobox

Prop	Type	Default	Description
items	Value[]	undefined	A flat array of items, or an array of groups with items.
value	Value	undefined	The selected value. Use when controlled.
defaultValue	Value	undefined	The initially selected value when uncontrolled.
onValueChange	(value, details) => void	—	Called when the selected value changes.
multiple	boolean	false	Whether multiple items can be selected.
disabled	boolean	false	Prevents interaction with the combobox.
readOnly	boolean	false	Prevents choosing a different option from the popup.
itemToStringLabel	(item: Value) => string	undefined	Converts an object item value to a display string. Not needed when items are already strings.
filter	(item, query, itemToString?) => boolean	built-in	Custom filter function used to match items against the input query.
autoHighlight	boolean	false	Highlights the first matching item automatically while filtering.

ComboboxInput

Prop	Type	Default	Description
placeholder	string	undefined	Placeholder text shown when the input is empty.

ComboboxItem

Prop	Type	Default	Description
value	Value	required	The value associated with this item.
disabled	boolean	false	Prevents selection of this item.

ComboboxContent

Prop	Type	Default	Description
sideOffset	number	6	Distance in pixels between the anchor and the popup.

Edit this page on GitHub

PreviousTabs NextCity Selector