What is Combobox?

A combobox combines a text field with a listbox. The user types to narrow a list of options, then chooses one. It sits between a plain select, which only allows picking from a fixed list, and a free text input, which allows anything. Country pickers, assignee fields, timezone selectors and tag inputs are all comboboxes. A variant that also accepts values not in the list is often called an autocomplete.

When to use it

• More than about ten options, where scrolling a select becomes slow and typing is faster.
• Options users know by name, such as people, countries or repositories.
• Remote data that has to be searched on the server as the user types.
• For five or fewer options, a radio group or segmented control shows every choice without a click.

Accessibility

The WAI-ARIA combobox pattern keeps DOM focus in the input the whole time. The input has role="combobox", aria-expanded for whether the popup is open, aria-controls pointing at the listbox, and aria-autocomplete="list" when typing filters the options. The popup has role="listbox" and each item role="option" with aria-selected. As the user moves through options, the input's aria-activedescendant is set to the highlighted option's id, which is how screen readers know what is active without focus leaving the field.

• Down Arrow opens the list and moves to the next option; Up Arrow moves back.
• Enter accepts the highlighted option and closes the list.
• Escape closes the list. Many implementations clear the input on a second Escape.
• Typing updates the filter; Home and End move the text cursor, not the highlight.

Announce the number of results in a polite live region, and show a visible empty state when nothing matches instead of an empty popup.

How to build one in React

Hand-building the pattern above is where most custom comboboxes fail, so start from a component that already handles it. MiniDev's Combobox takes items and a controlled value:

"use client"
import * as React from "react"
import { Combobox } from "@/components/ui/combobox"

const TIMEZONES = [
  { value: "America/New_York", label: "New York (UTC-5)" },
  { value: "Europe/Berlin", label: "Berlin (UTC+1)" },
  { value: "Asia/Kolkata", label: "Kolkata (UTC+5:30)" },
]

export function TimezoneField() {
  const [tz, setTz] = React.useState<string>()
  return <Combobox items={TIMEZONES} value={tz} onChange={setTz} placeholder="Pick a timezone" />
}

For several values use MultiSelect or TagsInput. When the combobox searches a server, debounce requests by 150 to 300ms and ignore responses that arrive out of order. The same list-in-a-popup mechanics power the command palette. Browse more inputs in the forms category.