Combobox
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
Loading interactive example…
View source
<script lang="ts"> import { combobox, useComboboxAPI, type ComboboxOption, type ComboboxValue, } from "phoundry-ui";
const api = useComboboxAPI();
const frameworkOptions: ComboboxOption[] = [ { value: "svelte", label: "Svelte", description: "Web framework", group: "Frontend", }, { value: "react", label: "React", description: "UI library", group: "Frontend", }, { value: "vue", label: "Vue", description: "Progressive framework", group: "Frontend", }, { value: "express", label: "Express", description: "Node.js framework", group: "Backend", }, { value: "fastify", label: "Fastify", description: "Fast Node.js server", group: "Backend", }, { value: "django", label: "Django", description: "Python framework", group: "Backend", }, ];
let singleValue = $state("");
function valueLabel(value: ComboboxValue): string { return Array.isArray(value) ? value.join(", ") : value; }
function setSingleValue(value: ComboboxValue) { singleValue = valueLabel(value); }</script>
<button type="button" class="rounded-md border border-border-default bg-surface-raised px-3 py-2 text-sm text-txt-primary" {@attach combobox({ api, options: frameworkOptions, value: singleValue, onchange: setSingleValue, placeholder: "Search frameworks...", })}> {singleValue || "Pick framework"}</button><p class="mt-2 text-xs text-txt-tertiary">Selected: {singleValue || "none"}</p>Input trigger search
Loading interactive example…
View source
<script lang="ts"> import { combobox, useComboboxAPI, type ComboboxOption, type ComboboxValue, } from "phoundry-ui";
const api = useComboboxAPI();
const frameworkOptions: ComboboxOption[] = [ { value: "svelte", label: "Svelte", description: "Web framework", group: "Frontend", }, { value: "react", label: "React", description: "UI library", group: "Frontend", }, { value: "vue", label: "Vue", description: "Progressive framework", group: "Frontend", }, { value: "express", label: "Express", description: "Node.js framework", group: "Backend", }, { value: "fastify", label: "Fastify", description: "Fast Node.js server", group: "Backend", }, { value: "django", label: "Django", description: "Python framework", group: "Backend", }, ];
let singleValue = $state("");
function valueLabel(value: ComboboxValue): string { return Array.isArray(value) ? value.join(", ") : value; }
function setSingleValue(value: ComboboxValue) { singleValue = valueLabel(value); }</script>
<div class="max-w-sm"> <input class="w-full rounded-md border border-border-default bg-surface-base px-3 py-2 text-sm text-txt-primary" placeholder="Search frameworks..." value={singleValue} {@attach combobox({ api, options: frameworkOptions, value: singleValue, onchange: setSingleValue, openOn: "focus", searchMode: "trigger", })} /></div>Multiple selection
Loading interactive example…
View source
<script lang="ts"> import { combobox, useComboboxAPI, type ComboboxOption, type ComboboxValue, } from "phoundry-ui";
const api = useComboboxAPI();
const frameworkOptions: ComboboxOption[] = [ { value: "svelte", label: "Svelte", description: "Web framework", group: "Frontend", }, { value: "react", label: "React", description: "UI library", group: "Frontend", }, { value: "vue", label: "Vue", description: "Progressive framework", group: "Frontend", }, { value: "express", label: "Express", description: "Node.js framework", group: "Backend", }, { value: "fastify", label: "Fastify", description: "Fast Node.js server", group: "Backend", }, { value: "django", label: "Django", description: "Python framework", group: "Backend", }, ];
let multiValue = $state<string[]>([]);
function setMultiValue(value: ComboboxValue) { multiValue = Array.isArray(value) ? value : [value].filter(Boolean); }</script>
<button type="button" class="rounded-md border border-border-default bg-surface-raised px-3 py-2 text-sm text-txt-primary" {@attach combobox({ api, options: frameworkOptions, value: multiValue, onchange: setMultiValue, multiple: true, placeholder: "Add frameworks...", })}> {multiValue.join(", ") || "Add frameworks"}</button><p class="mt-2 text-xs text-txt-tertiary"> Selected: {multiValue.join(", ") || "none"}</p>Creatable
Loading interactive example…
View source
<script lang="ts"> import { combobox, useComboboxAPI, type ComboboxOption, type ComboboxValue, } from "phoundry-ui";
const api = useComboboxAPI();
let creatableItems = $state<ComboboxOption[]>([ { value: "red", label: "Red" }, { value: "blue", label: "Blue" }, { value: "green", label: "Green" }, ]);
let creatableValue = $state("");
function valueLabel(value: ComboboxValue): string { return Array.isArray(value) ? value.join(", ") : value; }</script>
<div class="max-w-sm"> <input class="w-full rounded-md border border-border-default bg-surface-base px-3 py-2 text-sm text-txt-primary" placeholder="Pick or create a color..." value={creatableValue} {@attach combobox({ api, options: creatableItems, value: creatableValue, onchange: (value) => { creatableValue = valueLabel(value); }, creatable: true, onCreate: (query: string) => { creatableItems = [ ...creatableItems, { value: query.toLowerCase(), label: query }, ]; creatableValue = query.toLowerCase(); }, openOn: "focus", searchMode: "trigger", })} /></div>Async search
Loading interactive example…
View source
<script lang="ts"> import { combobox, useComboboxAPI, type ComboboxOption, type ComboboxValue, } from "phoundry-ui";
const api = useComboboxAPI();
const frameworkOptions: ComboboxOption[] = [ { value: "svelte", label: "Svelte", description: "Web framework", group: "Frontend", }, { value: "react", label: "React", description: "UI library", group: "Frontend", }, { value: "vue", label: "Vue", description: "Progressive framework", group: "Frontend", }, { value: "express", label: "Express", description: "Node.js framework", group: "Backend", }, { value: "fastify", label: "Fastify", description: "Fast Node.js server", group: "Backend", }, { value: "django", label: "Django", description: "Python framework", group: "Backend", }, ];
let asyncValue = $state("");
let asyncLoading = $state(false);
function valueLabel(value: ComboboxValue): string { return Array.isArray(value) ? value.join(", ") : value; }
async function mockRemoteSearch(query: string): Promise<ComboboxOption[]> { await new Promise((resolve) => setTimeout(resolve, 350)); const q = query.toLowerCase(); return frameworkOptions.filter( (option) => option.label.toLowerCase().includes(q) || option.description?.toLowerCase().includes(q), ); }</script>
<div class="max-w-sm"> <input class="w-full rounded-md border border-border-default bg-surface-base px-3 py-2 text-sm text-txt-primary" placeholder="Debounced remote filter..." value={asyncValue} {@attach combobox({ api, options: [], value: asyncValue, onchange: (value) => { asyncValue = valueLabel(value); }, onSearch: async (query: string) => { asyncLoading = true; try { return await mockRemoteSearch(query); } finally { asyncLoading = false; } }, openOn: "focus", searchMode: "trigger", })} /></div><p class="mt-2 text-xs text-txt-tertiary"> Selected: {asyncValue || "none"}{asyncLoading ? " (loading...)" : ""}</p>Custom option row
Loading interactive example…
View source
<script lang="ts"> import { Badge, PhiIcons, combobox, useComboboxAPI, type ComboboxOption, type ComboboxValue, } from "phoundry-ui";
const api = useComboboxAPI();
const frameworkOptions: ComboboxOption[] = [ { value: "svelte", label: "Svelte", description: "Web framework", group: "Frontend", }, { value: "react", label: "React", description: "UI library", group: "Frontend", }, { value: "vue", label: "Vue", description: "Progressive framework", group: "Frontend", }, { value: "express", label: "Express", description: "Node.js framework", group: "Backend", }, { value: "fastify", label: "Fastify", description: "Fast Node.js server", group: "Backend", }, { value: "django", label: "Django", description: "Python framework", group: "Backend", }, ];
let singleValue = $state("");
function valueLabel(value: ComboboxValue): string { return Array.isArray(value) ? value.join(", ") : value; }
function setSingleValue(value: ComboboxValue) { singleValue = valueLabel(value); }</script>
{#snippet optionRow( item: ComboboxOption, isActive: boolean, isSelected: boolean,)} <div class="flex w-full items-center justify-between gap-2 px-1 py-0.5"> <span class:text-accent-secondary={isActive} class="text-sm" >{item.label}</span > {#if item.description} <span class="max-w-[120px] truncate text-[10px] text-txt-tertiary" >{item.description}</span > {/if} {#if isSelected} <Badge color="blue" size="xs" icon={PhiIcons.check}>On</Badge> {/if} </div>{/snippet}
<button type="button" class="rounded-md border border-border-default bg-surface-raised px-3 py-2 text-sm text-txt-primary" {@attach combobox({ api, options: frameworkOptions, value: singleValue, onchange: setSingleValue, placeholder: "Framework...", option: optionRow, })}> {singleValue || "Framework..."}</button>Panel and option-row styling follows Context Menu through shared internal rendering. Search, async loading, creation, selection, and input focus remain Combobox behavior; its manager and attachment usage are unchanged.
ComboboxOptions
From phoundry-ui@0.4.21
| Name | Type | Default | Description |
|---|---|---|---|
options | ComboboxOptionsSource | undefined | — | Available options to search/select from |
value | ComboboxValue | undefined | — | Selected value(s) - string for single, string[] for multiple |
onchange | ((value: ComboboxValue) => void) | undefined | — | Called when selection changes |
onSearch | ((query: string) => Promise<ComboboxOption[]>) | undefined | — | Async search callback - replaces local filtering |
onCreate | ((query: string) => void) | undefined | — | Called when user creates a new option |
placeholder | string | undefined | — | Input placeholder text |
multiple | boolean | undefined | — | Enable multi-select with tags |
creatable | boolean | undefined | — | Allow creating new options from the query |
size | "sm" | "md" | undefined | — | Field typography and padding aligned to Button control scale |
option | Snippet<[item: ComboboxOption, isActive: boolean, isSelected: boolean]> | undefined | — | Custom snippet for rendering each option row |
actions | MenuItem[] | undefined | — | Menu items pinned below the scrolling options, unaffected by search. Supports all Context Menu item types and preventClose. |
disabled: Disables the combobox
class: Additional CSS classes on the wrapper
id: HTML id attribute
name: HTML name attribute
element: Bindable reference to the input element
Other native attributes: Forwarded to the search <input> (e.g. autocomplete, spellcheck).
Usage tips
- Use
onSearchfor server-side filtering - it debounces at 200 ms and replaces local filtering entirely. - Combine
multiple+creatablefor a tag-input pattern where users can add arbitrary values. - Provide the
optionsnippet to render custom layouts (avatars, badges, etc.) inside each dropdown row.
Footer actions
Pass actions: MenuItem[] to combobox(), api.open(), or api.configure() to pin menu items below the scrolling option list. They remain visible when you scroll or search, including when no options match. The footer supports Context Menu actions, boolean and radio items, separators, labels, groups, custom rows, and submenus.
import type { MenuItem } from "phoundry-ui";
const actions: MenuItem[] = [ { type: "action", id: "refresh", label: "Refresh projects", preventClose: true, action: () => refreshProjects(), }, { type: "separator" }, { type: "action", id: "new-project", label: "New project…", shortcut: "Mod+N", action: () => createProject(), },];
api.open({ anchor: trigger, options: projects, onchange: selectProject, actions,});Footer actions close the Combobox before running unless preventClose: true. Top-level action shortcuts also work while focus is in the option list or search field. Arrow keys move between options and footer rows; footer submenus and custom controls own their keyboard interaction.
The previous { id, label, run } footer shape is replaced by the shared { type: 'action', id, label, action } shape. ComboboxAction now aliases ActionMenuItem.
CSS styling
.ph-combobox-panel is the stable identification hook for Combobox. Part selectors and --_ph-* properties are internal. Component CSS is scoped and unlayered; Consumer classes remain additive and utility overrides may lose precedence.
Searchable option rows share the overlay-row visual contract. Active and selected rows use semantic state; keyboard and selection behavior are unchanged.
Keep the shared component stylesheet and a named Theme imported. Decorative motion respects reduced-motion preferences.