Skip to content

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
button-trigger.svelte
<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>

Loading interactive example…

View source
input-trigger-search.svelte
<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
multiple-selection.svelte
<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
creatable.svelte
<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>

Loading interactive example…

View source
async-search.svelte
<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
custom-option-row.svelte
<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

NameTypeDefaultDescription
optionsComboboxOptionsSource | undefined—Available options to search/select from
valueComboboxValue | 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
placeholderstring | undefined—Input placeholder text
multipleboolean | undefined—Enable multi-select with tags
creatableboolean | undefined—Allow creating new options from the query
size"sm" | "md" | undefined—Field typography and padding aligned to Button control scale
optionSnippet<[item: ComboboxOption, isActive: boolean, isSelected: boolean]> | undefined—Custom snippet for rendering each option row
actionsMenuItem[] | 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 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.

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.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.