Combobox
A text input that filters a list as you type, for picking one or many items from long lists.
npx prodular-ui add comboboxSingle
Type to filter teammates.
Type to filter. The owner gets renewal reminders.
"use client"
import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList,} from "@/components/ui/combobox"import { Field, FieldDescription, FieldLabel } from "@/components/ui/field"
const owners = [ "Maya Okafor", "Daniel Reyes", "Priya Raman", "Tomas Lindqvist", "Hana Sato", "Elliot Brooks", "Amara Nwosu",]
export default function ComboboxDefault() { return ( <Field className="max-w-xs"> <FieldLabel>Account owner</FieldLabel> <Combobox items={owners}> <ComboboxInput placeholder="Search teammates" className="w-full" /> <ComboboxContent> <ComboboxEmpty>No teammate matches that name.</ComboboxEmpty> <ComboboxList> {(item: string) => ( <ComboboxItem key={item} value={item}> {item} </ComboboxItem> )} </ComboboxList> </ComboboxContent> </Combobox> <FieldDescription>Type to filter. The owner gets renewal reminders.</FieldDescription> </Field> )}Multiple with chips
Billing
API
"use client"
import * as React from "react"
import { Combobox, ComboboxChip, ComboboxChips, ComboboxChipsInput, ComboboxContent, ComboboxEmpty, ComboboxItem, ComboboxList, ComboboxValue, useComboboxAnchor,} from "@/components/ui/combobox"
const labels = ["Bug", "Billing", "Onboarding", "Performance", "Mobile", "API", "Security", "Docs"]
export default function ComboboxMultiple() { const anchor = useComboboxAnchor() return ( <Combobox multiple autoHighlight items={labels} defaultValue={["Billing", "API"]}> <ComboboxChips ref={anchor} className="w-full max-w-sm"> <ComboboxValue> {(values: string[]) => ( <React.Fragment> {values.map((value) => ( <ComboboxChip key={value}>{value}</ComboboxChip> ))} <ComboboxChipsInput placeholder={values.length ? "" : "Add labels"} aria-label="Labels" /> </React.Fragment> )} </ComboboxValue> </ComboboxChips> <ComboboxContent anchor={anchor}> <ComboboxEmpty>No label with that name.</ComboboxEmpty> <ComboboxList> {(item: string) => ( <ComboboxItem key={item} value={item}> {item} </ComboboxItem> )} </ComboboxList> </ComboboxContent> </Combobox> )}Sizes with clear button
"use client"
import { Combobox, ComboboxContent, ComboboxEmpty, ComboboxInput, ComboboxItem, ComboboxList,} from "@/components/ui/combobox"
const projects = ["Atlas redesign", "Billing v2", "Mobile onboarding", "Search relevance", "SOC 2 audit"]
export default function ComboboxSizes() { return ( <div className="flex w-full max-w-xs flex-col gap-3"> {(["sm", "default", "lg"] as const).map((size) => ( <Combobox key={size} items={projects}> <ComboboxInput size={size} placeholder="Find a project" aria-label="Project" showClear /> <ComboboxContent> <ComboboxEmpty>No project found.</ComboboxEmpty> <ComboboxList> {(item: string) => ( <ComboboxItem key={item} value={item}> {item} </ComboboxItem> )} </ComboboxList> </ComboboxContent> </Combobox> ))} </div> )}Anatomy
<Combobox items={owners}> <ComboboxInput placeholder="Search teammates" /> <ComboboxContent> <ComboboxEmpty>No teammate matches that name.</ComboboxEmpty> <ComboboxList> {(item) => <ComboboxItem key={item} value={item}>{item}</ComboboxItem>} </ComboboxList> </ComboboxContent></Combobox>Guidance
Use it when
- Long lists people search by name: teammates, customers, projects, countries.
- Tagging, where several values can apply. Use chips.
Avoid
- Short lists of fixed options. Use Select.
- Free text search with no list. Use Input or InputGroup.
Rules for AI agents
Published in llms-full.txt, the registry and the MCP server, so coding agents follow them when they build with this component.
- Pass the full list as items and render ComboboxList as a function of each item.
- Always include ComboboxEmpty with a sentence that says what was not found.
- For multiple values use ComboboxChips with useComboboxAnchor and pass the anchor to ComboboxContent.
- Outside a Field, give ComboboxInput or ComboboxChipsInput an aria-label.
- Use showClear when an empty value is valid.
- Put a search icon or scope label in ComboboxInput leading instead of absolutely positioning it.
API
Combobox
| Prop | Type | Default | Description |
|---|---|---|---|
| items | T[] | The options to filter. | |
| multiple | boolean | false | Allows several values. Pair with ComboboxChips. |
ComboboxInput
| Prop | Type | Default | Description |
|---|---|---|---|
| size | "sm" | "default" | "lg" | "default" | Height. Matches Button and Input. |
| showTrigger | boolean | true | Shows the chevron button. |
| showClear | boolean | false | Shows a clear button when there is a value. |
| leading | ReactNode | Content before the text, such as a search icon, in an inline-start addon. |
ComboboxContent
| Prop | Type | Default | Description |
|---|---|---|---|
| anchor | RefObject | Positions the popup against the chips container. |
Installation
The Prodular UI CLI adds the source to components/ui with everything it depends on. In a project that already uses shadcn/ui, the shadcn CLI installs it from the Prodular registry too. See Installation for the first setup.
npx prodular-ui add combobox# or, with the registry in components.jsonnpx shadcn@latest add @prodular/combobox