Combobox Experimental

Searchable dropdown with type-ahead filtering, multi-select with tags, async search, creatable options, option groups, and custom option rendering via snippets.

import { Combobox } from 'phoundry-ui';

Basic Search

Selected: none

Show code

<Combobox
  options={frameworks}
  value={selected}
  onchange={(v) => selected = v as string}
  placeholder="Search frameworks..."
/>

Multiple with Tags

Selected: none

Show code

<Combobox
  options={frameworks}
  value={tags}
  onchange={(v) => tags = v as string[]}
  multiple
  placeholder="Add frameworks..."
/>

Creatable

Show code

<Combobox
  options={items}
  value={selected}
  onchange={(v) => selected = v as string}
  creatable
  onCreate={(val) => {
    items = [...items, { value: val.toLowerCase(), label: val }];
    selected = val.toLowerCase();
  }}
  placeholder="Pick or create a color..."
/>

Async search (onSearch)

While onSearch is set, local options filtering is skipped — show your own loading UI alongside if needed.

Selected: none

Show code

<Combobox
  value={pick}
  onchange={(v) => pick = v as string}
  onSearch={async (q) => await api.search(q)}
  placeholder="Type to query server…"
/>

Small + disabled

Show code

<Combobox size="sm" ... />
<Combobox disabled ... />

Custom option row

Show code

{#snippet optionRow(item, isActive, isSelected)}
  …
{/snippet}

<Combobox {options} value={v} onchange={...} option={optionRow} />

Props

Prop	Type	Default	Description
options	ComboboxOption[]	[]	Available options to search/select from
value	string \| string[]	—	Selected value(s) — string for single, string[] for multiple
onchange required	(value: string \| string[]) => void	—	Called when selection changes
onSearch	(query: string) => Promise<ComboboxOption[]>	—	Async search callback — replaces local filtering
onCreate	(query: string) => void	—	Called when user creates a new option
placeholder	string	'Search...'	Input placeholder text
multiple	boolean	false	Enable multi-select with tags
creatable	boolean	false	Allow creating new options from the query
disabled	boolean	false	Disables the combobox
size	'sm' \| 'md'	'md'	Field typography and padding aligned to Button control scale
class	string	—	Additional CSS classes on the wrapper
id	string	—	HTML id attribute
name	string	—	HTML name attribute
element	HTMLInputElement	—	Bindable reference to the input element
option	Snippet<[item, isActive, isSelected]>	—	Custom snippet for rendering each option row
...rest	Record<string, unknown>	—	Forwarded to the search `<input>` (e.g. `autocomplete`, `spellcheck`).

Usage tips

Use onSearch for server-side filtering — it debounces at 200 ms and replaces local filtering entirely.
Combine multiple + creatable for a tag-input pattern where users can add arbitrary values.
Provide the option snippet to render custom layouts (avatars, badges, etc.) inside each dropdown row.