Combobox

Searchable combobox with a morphing portal, grouped filtering, keyboard navigation, and controlled or uncontrolled state.

Preview

Workspace

Install

Add it with the shadcn CLI, or copy the source manually.

$ bunx --bun shadcn add @beui/combobox

API Reference

ComboboxContent

side?
"top" | "bottom"
bottom
align?
"start" | "center" | "end"
start
sideOffset?
number
6
avoidCollisions?
boolean
true
className?
string

Combobox

value?
string
defaultValue?
string
onValueChange?
((value: string) => void)
open?
boolean
defaultOpen?
boolean
false
onOpenChange?
((open: boolean) => void)
query?
string
defaultQuery?
string
onQueryChange?
((query: string) => void)
filter?
ComboboxFilter
(value, query, keywords) => { const needle = query.trim().toLocaleLowerCase(); if (!needle) return true; const haystack = [value, ...keywords].join(" ").toLocaleLowerCase(); let queryIndex = 0; for (const character of haystack) { if (character === needle[queryIndex]) queryIndex += 1; if (queryIndex === needle.length) return true; } return false; }
disabled?
boolean
false
className?
string

ComboboxEmpty

className?
string

ComboboxGroup

className?
string

ComboboxItem

value
string
textValue?
string
keywords?
{}
[]
disabled?
boolean
false
onSelect?
((value: string) => void)
className?
string

ComboboxLabel

className?
string

ComboboxList

ariaLabel?
string
Options
className?
string

ComboboxSeparator

className?
string

ComboboxInput

ref?
any
wrapperClassName?
string

ComboboxTrigger

className?
string

ComboboxValue

placeholder?
any
Select an option
className?
string

Composition

Place the searchable input inside the trigger, then compose listbox primitives inside the portalled content.

Combobox
├── ComboboxTrigger
│   └── ComboboxInput
└── ComboboxContent
    └── ComboboxList
        ├── ComboboxEmpty
        ├── ComboboxGroup
        │   ├── ComboboxLabel
        │   └── ComboboxItem
        └── ComboboxSeparator

How it works

A combobox combines text input with a filtered listbox while keeping focus in the input. It manages search, active-option navigation, selection, and portal positioning without owning the option data or surrounding form.

Keep in mind

Some components on this site are inspired by or recreated from existing work across the web. I'm not here to take credit; just to learn, experiment, and sometimes push things a bit further. If something looks familiar and I forgot to mention you, reach out and I'll fix that right away.

Updated