Combobox

​

When to use

• More than ~12 options, where typing to filter is faster than scrolling.
• The user knows roughly what they’re looking for (e.g. selecting a country, an asset name, a tag)
• Forms where users need to search and select from a predefined list.
• When users need to add new options that don’t exist in the list yet.

​

When to use something else

• Fewer than ~12 options: use Select, Radio, or Checkbox depending on context.
• The user is unfamiliar with the available options and wouldn’t know what to type: a visible list is less intimidating.
• Very large datasets where filtering may cause lag: consider a Data grid with toolbar filtering instead.
• Free text input with no list to select from: use Input or Textarea.

​

Dos and don’ts

• Do group related options if the list spans multiple categories.
• Do use clearable Badges when a user can select multiple options as this allows for quick and easy clearing.
• Do left align with other input fields when used in a form.
• Don’t use it for simple yes/no or small option sets: the search affordance implies more options than are there.
• Don’t use default selections as users may not thoroughly check the default.
• Don’t make the menu smaller than the Combobox input field.

​

Behavior

• Single-select: the menu closes immediately on selection.
• Multi-select: the menu stays open until the user clicks outside, presses Escape, or presses Enter.
• Searching: users can search for an item by typing in the input field. As the user types, the list items should filter out if they don’t match the searched content. Searched strings should be highlighted in the list to help the user easily identify what they are looking for.
• Adding items: users can add an item by typing the item in the input field and hitting Enter or Return on the keyboard or the “Add + [label item]” button at the bottom of the list. Adding the item automatically selects it.
• Clearing items: there are four ways in which content can be cleared from the input area:
  • The user can deselect menu items to remove them from the input area.
  • The user can input their cursor anywhere in the input and hit Delete or backspace on their keyboard. This method works for both strings and Filter chips.
  • The user can clear individual Filter chips but clicking the “X” icon button inside the chip.
  • Combobox can optionally display a Clear all button to the right of the text, but left of the chevron, allowing the user to quickly clear all content within the field. Clear all buttons are not displayed until after a user has input content.

​

Combobox menu

​

Often used with

​

Accessibility

• Explicit labeling: Pass an aria-label or aria-labelledby to the PopoverTrigger button, or associate it with an external <Label> element using matching htmlFor and id attributes.
• Form validation and error states: Apply aria-invalid="true" to the trigger button when validation fails, and link error messages via aria-describedby="error-message-id".
• Custom option content: If rendering icons, status badges, or subtext inside a <CommandItem>, wrap hidden contextual details in <span className="sr-only"> so screen readers hear more than just visual fragments.
• Trigger text and placeholders: Ensure the trigger button displays meaningful visual text when an item is selected, rather than a visual-only icon or blank state.
• Custom styling and focus rings: If overriding default Tailwind classes, preserve visible focus rings (focus-visible:ring-2) on the trigger and maintain a minimum 4.5:1 text/icon contrast ratio across hovered, selected, and disabled option states.

​

Visual examples

​

Composed