Combobox
A field you type into, with a panel of the items your app supplies for that text: one value, several as chips, or whatever was typed.
Installation
npx shadcn@latest add @flyingsalmon/comboboxUsage
import { useState } from 'react'
import { Combobox, ComboboxItem, ComboboxMode } from '@/components/ui/combobox'
export function ComboboxUsage() {
const [placeId, setPlaceId] = useState<string | null>(null)
return (
<Combobox
mode={ComboboxMode.Single}
label="Destination"
value={placeId}
onValueChange={setPlaceId}
>
<ComboboxItem value="place-lisbon">Lisbon</ComboboxItem>
<ComboboxItem value="place-hanoi">Hanoi</ComboboxItem>
</Combobox>
)
}Examples
Filtering the list
The combobox shows exactly the items you pass. Read the text through onInputValueChange and pass the matches.
Remote results
Debounce and fetch in your own code, show loading while the request runs, and render ComboboxEmpty when nothing comes back. The panel opens when the results land, unless the traveller has pressed Escape or left the field. Type r or ha for matches, zz for none.
Groups, icons, and descriptions
Groups take a label and a separator between them. An item's icon sits before its label and its description after; a disabled item keeps its place.
Free text as the value
With allowFreeText, a pick reports the item's key and anything else typed is reported as itself when the field loses focus.
No destination yet
Several values as chips
Multiple mode takes a string array. A pick adds a chip, keeps the panel open, and clears the text for the next search; picking a checked item removes it.
Chips from free text
With allowFreeText in multiple mode, Enter with nothing highlighted turns the typed text into a chip.
Description
Helper text under the field. It stays put when an error arrives.
Where the trip starts
Error
The field shows its own error under the box until the value is fixed. Pick a city to clear it.
Pick the city you fly from
Disabled
Dims the field and takes it out of the tab order.
Small size
Matches the small Input and Select, for dense filter bars.
In a form
name posts the picked key with the form. Submit with no destination to see the field's error; plan the trip and the new trip appears above the form.
Guidelines
When to use
- To choose from a list too long to scan, where typing is faster: a destination, a departure city.
- To collect several values as chips: interests, the travellers on a trip.
- To accept an answer that may not be on the list, such as a place nobody has added yet.
When not to use
- Use Select for a short, fixed list such as a cabin class, where scanning beats typing.
- Use Radio group for two to five options that should all stay visible while the traveller decides.
- Use Input for free text that needs no suggestions.
Do and don’t
- DoWhen a search finds nothing, say so in the panel and say what to try next: "No city or country called Kyto. Check the spelling, or try the country."A panel that never opens looks broken. The empty row shows the search ran and points the traveller at their next attempt.
- DoTell look-alike results apart with a muted region after each name, such as "Portland · Oregon".Many places share a name. The region lets the traveller pick the right one at a glance, without opening a map.
- Don’tGive every item the same icon.An icon earns its place by telling kinds apart, such as a city from a country. The same icon on every row is noise.
- DoOnce a field holds chips, change its placeholder to invite another, such as "Add another".The chips show the answer so far, and the prompt says more is welcome, so a traveller with one destination knows the field takes several.
- Don’tOpen the panel on focus.Tabbing through a form would throw a panel over the next field. The panel opens on typing, the arrow keys, or the chevron, and when results land after typing.
Accessibility
| Key | Description |
|---|---|
| ArrowDownArrowUp | Opens the panel, then moves the highlight through the items. |
| Enter | Picks the highlighted item. In multiple mode it toggles the item and keeps the panel open; with free text and no highlight, it adds the typed text as a chip. |
| Escape | Closes the panel and keeps the typed text. |
| TabShift+Tab | Closes the panel without picking and moves to the next field. In single mode without free text, leaving with the text erased clears the pick. |
| HomeEnd | Move the caret to either end of the text, never the highlight. |
| Backspace | In multiple mode with an empty input, removes the last chip. |
| ArrowLeftArrowRight | In multiple mode, ArrowLeft at the start of the input focuses the last chip; both keys then move between chips and back to the input. |
| BackspaceDelete | On a focused chip, removes it. |
The input is the only tab stop: the clear and chevron buttons are labelled but stay out of the tab order. Focus never leaves the input while the panel is open; the highlighted row is the focus indicator, wired through aria-activedescendant.
description and error join the input’s accessible description, error first. required sets aria-required, loading sets aria-busy, and ComboboxEmpty is announced politely when it appears. An item’s icon is hidden from screen readers, so only its label is read.
API
Combobox
className styles the wrapper that holds the label, the field, and the messages.
| Prop | Type | Default | Description |
|---|---|---|---|
| mode | ComboboxMode | Required | Single takes one value; Multiple takes several as chips. There is no default. |
| value | string | null | string[] | Required | The picked key or keys, or typed text when free text is on. A string array in Multiple mode. |
| onValueChange | (value) => void | Required | Called with the next value. |
| children | ReactNode | – | The items to show for the current text, with any groups, labels, separators, and an empty row. An item may sit inside your own component, such as a TripOption that returns ComboboxItem. The combobox filters nothing and shows exactly what you pass, so filtering, fetching, debouncing, and cancelling a billed call stay in your code. |
| label | string | – | The visible label. Renders above the field and is wired to it. |
| placeholder | string | – | Shown while the input is empty. |
| description | string | – | Helper text under the field. |
| error | string | – | The failure message. Turns the border, the ring, and the label destructive. |
| allowFreeText | boolean | false | Keeps typed text as the value instead of reverting it on blur. |
| inputValue | string | – | The controlled text in the input. |
| onInputValueChange | (inputValue: string) => void | – | Called on every keystroke and pick. Filter or fetch from here. |
| loading | boolean | false | Shows a spinner in the field while your results load. |
| size | ComboboxSize | ComboboxSize.Default | Default and Small match the field heights of the same names. |
| disabled | boolean | false | Dims the field and its label and removes both from the tab order. |
| name | string | – | Posts a hidden input per value with the surrounding form. A disabled combobox posts nothing. |
| required | boolean | false | Marks the label and sets aria-required. |
| open | boolean | – | The controlled open state of the panel. |
| defaultOpen | boolean | – | The initial open state when uncontrolled. |
| onOpenChange | (open: boolean) => void | – | Called when the panel opens or closes. |
| side | PanelSide | PanelSide.Bottom | Which side of the field the panel prefers. |
| align | PanelAlign | PanelAlign.Start | How the panel lines up along that side. |
| id | string | – | The input id. Generated when left out. |
ComboboxItem
| Prop | Type | Default | Description |
|---|---|---|---|
| value | string | Required | The key reported when the item is picked. Use an id, not the label: with free text on, typed text that equals a key reads as a pick. |
| children | string | Required | The label, shown in the list, the input, and the chip. |
| description | string | – | Muted text after the label, truncated to fit. |
| icon | ReactNode | – | An icon before the label, in the list only. |
| disabled | boolean | false | Keeps the item in place but out of reach. |
| onClick | (event: MouseEvent) => void | – | Runs before the pick. Call event.preventDefault() to cancel the pick. |
| ref | Ref<HTMLDivElement> | – | Receives the option element. |
ComboboxGroup, ComboboxLabel, ComboboxSeparator, and ComboboxEmpty take the props of a <div>. There is no input, trigger, or content part: the root renders them. Pass ComboboxEmpty with your message when a search returns nothing. There is no footer slot, so a source’s credit line goes under the field, in your own markup.