Skip to content
flyingsalmon

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/combobox

Usage

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.

museums

Chips from free text

With allowFreeText in multiple mode, Enter with nothing highlighted turns the typed text into a chip.

traveller-brian

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.

food

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.

mmddyyyy
mmddyyyy

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

  • Do
    When 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.
  • Do
    Tell 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’t
    Give 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.
  • Do
    Once 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’t
    Open 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

KeyDescription
ArrowDownArrowUpOpens the panel, then moves the highlight through the items.
EnterPicks 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.
EscapeCloses the panel and keeps the typed text.
TabShift+TabCloses the panel without picking and moves to the next field. In single mode without free text, leaving with the text erased clears the pick.
HomeEndMove the caret to either end of the text, never the highlight.
BackspaceIn multiple mode with an empty input, removes the last chip.
ArrowLeftArrowRightIn multiple mode, ArrowLeft at the start of the input focuses the last chip; both keys then move between chips and back to the input.
BackspaceDeleteOn 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.

PropTypeDefaultDescription
modeComboboxModeRequiredSingle takes one value; Multiple takes several as chips. There is no default.
valuestring | null | string[]RequiredThe picked key or keys, or typed text when free text is on. A string array in Multiple mode.
onValueChange(value) => voidRequiredCalled with the next value.
childrenReactNode–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.
labelstring–The visible label. Renders above the field and is wired to it.
placeholderstring–Shown while the input is empty.
descriptionstring–Helper text under the field.
errorstring–The failure message. Turns the border, the ring, and the label destructive.
allowFreeTextbooleanfalseKeeps typed text as the value instead of reverting it on blur.
inputValuestring–The controlled text in the input.
onInputValueChange(inputValue: string) => void–Called on every keystroke and pick. Filter or fetch from here.
loadingbooleanfalseShows a spinner in the field while your results load.
sizeComboboxSizeComboboxSize.DefaultDefault and Small match the field heights of the same names.
disabledbooleanfalseDims the field and its label and removes both from the tab order.
namestring–Posts a hidden input per value with the surrounding form. A disabled combobox posts nothing.
requiredbooleanfalseMarks the label and sets aria-required.
openboolean–The controlled open state of the panel.
defaultOpenboolean–The initial open state when uncontrolled.
onOpenChange(open: boolean) => void–Called when the panel opens or closes.
sidePanelSidePanelSide.BottomWhich side of the field the panel prefers.
alignPanelAlignPanelAlign.StartHow the panel lines up along that side.
idstring–The input id. Generated when left out.

ComboboxItem

PropTypeDefaultDescription
valuestringRequiredThe 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.
childrenstringRequiredThe label, shown in the list, the input, and the chip.
descriptionstring–Muted text after the label, truncated to fit.
iconReactNode–An icon before the label, in the list only.
disabledbooleanfalseKeeps the item in place but out of reach.
onClick(event: MouseEvent) => void–Runs before the pick. Call event.preventDefault() to cancel the pick.
refRef<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.

  • Select

    A short, fixed list with no typing.
  • Input

    Free text with no suggestions.
  • Date picker

    The field for a date or a range of dates.
  • Form

    Lays fields out with an actions row and a result slot.