Examples
Search local options
Type to filter a fixture list with the built-in matcher.
Searchable project owner picker
"use client";
import {
Combobox,
ComboboxContent,
ComboboxEmpty,
ComboboxInput,
ComboboxInputGroup,
ComboboxItem,
ComboboxLabel,
ComboboxList,
ComboboxTrigger,
} from "@phuctech/ui/components/combobox";
type Owner = { value: string; label: string; team: string };
const owners: Owner[] = [
{ value: "ava", label: "Ava Nguyen", team: "Design" },
{ value: "minh", label: "Minh Tran", team: "Engineering" },
{ value: "linh", label: "Linh Pham", team: "Research" },
];
export function Example() {
return (
<Combobox items={owners} itemToStringLabel={(owner) => owner.label} itemToStringValue={(owner) => owner.value}>
<ComboboxLabel htmlFor="owner-search">Project owner</ComboboxLabel>
<ComboboxInputGroup className="mt-1.5">
<ComboboxInput id="owner-search" placeholder="Search people" />
<ComboboxTrigger aria-label="Show people" />
</ComboboxInputGroup>
<ComboboxContent>
<ComboboxEmpty>No people match that search.</ComboboxEmpty>
<ComboboxList>
{(owner: Owner) => <ComboboxItem key={owner.value} value={owner}>{owner.label}<span className="ml-2 text-xs text-muted-foreground">{owner.team}</span></ComboboxItem>}
</ComboboxList>
</ComboboxContent>
</Combobox>
);
}
Choose multiple options
Keep selected option objects in feature state.
Multiple notification channel picker
"use client";
import { useState } from "react";
import {
Combobox,
ComboboxContent,
ComboboxEmpty,
ComboboxInput,
ComboboxInputGroup,
ComboboxItem,
ComboboxLabel,
ComboboxList,
ComboboxTrigger,
} from "@phuctech/ui/components/combobox";
type Channel = { value: string; label: string };
const channels: Channel[] = [
{ value: "email", label: "Email" },
{ value: "push", label: "Push notification" },
{ value: "sms", label: "Text message" },
];
export function Example() {
const [value, setValue] = useState<Channel[]>([channels[0]!]);
return (
<Combobox items={channels} multiple value={value} onValueChange={setValue}>
<ComboboxLabel htmlFor="channel-search">Notification channels</ComboboxLabel>
<ComboboxInputGroup className="mt-1.5">
<ComboboxInput id="channel-search" placeholder="Add channels" />
<ComboboxTrigger aria-label="Show notification channels" />
</ComboboxInputGroup>
<ComboboxContent>
<ComboboxEmpty>No channels found.</ComboboxEmpty>
<ComboboxList>
{(channel: Channel) => <ComboboxItem key={channel.value} value={channel}>{channel.label}</ComboboxItem>}
</ComboboxList>
</ComboboxContent>
</Combobox>
);
}
Callback search
The application receives a debounced query and supplies the current result options.
Combobox callback search preview
"use client";
import { useState } from "react";
import {
Combobox,
ComboboxContent,
ComboboxEmpty,
ComboboxInput,
ComboboxInputGroup,
ComboboxItem,
ComboboxLabel,
ComboboxList,
ComboboxStatus,
ComboboxTrigger,
} from "@phuctech/ui/components/combobox";
type Project = { value: string; label: string };
const projects: Project[] = [
{ value: "atlas", label: "Atlas redesign" },
{ value: "billing", label: "Billing refresh" },
{ value: "mobile", label: "Mobile onboarding" },
];
export function Example() {
const disabled = false;
const [value, setValue] = useState<Project | null>(null);
const [results, setResults] = useState(projects);
function handleSearch(query: string) {
const normalized = query.toLocaleLowerCase();
setResults(projects.filter((project) => project.label.toLocaleLowerCase().includes(normalized)));
}
return (
<Combobox
items={projects}
filteredItems={results}
filter={null}
value={value}
onValueChange={setValue}
onSearch={handleSearch}
disabled={disabled}
itemToStringLabel={(project) => project.label}
>
<ComboboxLabel htmlFor="project-search">Project</ComboboxLabel>
<ComboboxInputGroup className="mt-1.5">
<ComboboxInput id="project-search" placeholder="Search projects" />
<ComboboxTrigger aria-label="Show projects" />
</ComboboxInputGroup>
<ComboboxContent>
<ComboboxStatus>Search results come from application state.</ComboboxStatus>
<ComboboxEmpty>No matching projects.</ComboboxEmpty>
<ComboboxList>
{(project: Project) => <ComboboxItem key={project.value} value={project}>{project.label}</ComboboxItem>}
</ComboboxList>
</ComboboxContent>
</Combobox>
);
}
When to use
Use Combobox when a person needs to search a known option set while keeping listbox keyboard behavior. Single values and multiple values are owned by the feature. For callback search, Combobox waits 350 ms by default, calls onSearch with the query, and leaves requests, race handling, loading/error state, and refreshed options to the application. The callback is not awaited and no request is made by the component.
Usage
import {
Combobox,
ComboboxContent,
ComboboxEmpty,
ComboboxInput,
ComboboxInputGroup,
ComboboxItem,
ComboboxLabel,
ComboboxList,
} from "@phuctech/ui/components/combobox";
type Person = { value: string; label: string };
const people: Person[] = [{ value: "ava", label: "Ava Nguyen" }];
<Combobox items={people} onSearch={(query) => loadPeople(query)}>
<ComboboxLabel htmlFor="person-search">Person</ComboboxLabel>
<ComboboxInputGroup>
<ComboboxInput id="person-search" placeholder="Search people" />
</ComboboxInputGroup>
<ComboboxContent>
<ComboboxEmpty>No people found.</ComboboxEmpty>
<ComboboxList>
{(person: Person) => <ComboboxItem key={person.value} value={person}>{person.label}</ComboboxItem>}
</ComboboxList>
</ComboboxContent>
</Combobox>When onSearch is supplied, local filtering defaults off so the application can replace items or supply filteredItems. Search results remain fixture data in documentation examples; applications own network requests and stale-response protection.
API
Tokens
Accessibility
- Provide a visible ComboboxLabel connected to the input, or an explicit accessible name.
- Base UI provides listbox keyboard navigation, option selection, and popup focus behavior; disabled options stay out of selection.
- Use ComboboxStatus for externally owned loading or error messages and ComboboxEmpty for a settled empty list.
- Do not rely on color alone to communicate selected, disabled, loading, or error states.
Do and don’t
Debounce live search and update the option list from the feature that owns the request.
Start a network request per keystroke or assume an older response is still current.