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';

Button trigger

Selected: none

import { combobox, useComboboxAPI } from 'phoundry-ui';

const api = useComboboxAPI();

<button
  {@attach combobox({
    api,
    options,
    value,
    onchange: (next) => (value = next as string)
  })}
>
  Pick framework
</button>

Input trigger search

<input
  {@attach combobox({
    api,
    options,
    value,
    onchange,
    openOn: 'focus',
    searchMode: 'trigger'
  })}
/>

Multiple selection

Selected: none

<button
  {@attach combobox({
    api,
    options,
    value: tags,
    onchange: (next) => (tags = next as string[]),
    multiple: true
  })}
>
  Add frameworks
</button>

Creatable

<input
  {@attach combobox({
    api,
    options: items,
    value,
    onchange,
    creatable: true,
    onCreate: (query) => {
      items = [...items, { value: query.toLowerCase(), label: query }];
      value = query.toLowerCase();
    },
    openOn: 'focus',
    searchMode: 'trigger'
  })}
/>

Async search

Selected: none

<input
  {@attach combobox({
    api,
    options: [],
    value,
    onchange,
    onSearch: async (query) => await api.search(query),
    openOn: 'focus',
    searchMode: 'trigger'
  })}
/>

Custom option row

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

<button {@attach combobox({ api, options, value, onchange, option: optionRow })}>
  Pick framework
</button>

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.