Inputs/Combobox

Combobox

Autocomplete input and command palette with a list of suggestions.

Themed

When to Use

Use Combobox when you need to:

Provide a searchable dropdown for selecting from a large list of options
Allow users to filter and find items quickly with type-ahead search
Build autocomplete inputs for forms (e.g., country, language, framework pickers)
Create status pickers or label selectors with inline search
Combine selection with a command palette-style interface

When Not to Use

Short lists with fewer than 5 options -- use Select or Radio Group instead
Simple dropdowns without search -- use Select for basic selection
Full command palette functionality -- use Command as a standalone dialog
Free-text input where any value is valid -- use Input with suggestions

Default

A searchable dropdown that allows users to select from a list of options. Built using Popover and Command components.

Status Picker

A combobox styled as a status picker with a side-positioned popover. Useful for task management and workflow tools.

Status

With Dropdown Menu

Combine combobox with dropdown menu for complex action menus featuring searchable sub-menus and label assignment.

featureCreate a new project

Form Integration

A combobox integrated into a form with label and description. The popover width matches the trigger for a polished layout.

Framework

Select the framework you want to use for your project.

UX & Design Guidelines

Visual Hierarchy

The combobox trigger should visually resemble other form inputs in your layout. Use variant="outline" for the trigger button to maintain consistency with standard input fields. Include a chevron icon to signal that the element is expandable.

Spacing & Layout

Set a consistent width on both the trigger and the popover content (e.g., w-[200px]). For form layouts, use w-[--radix-popover-trigger-width] on the popover to match the trigger width automatically. Place the combobox within standard form spacing using gap-4 between fields.

Responsive Behavior

On mobile, ensure the popover content does not overflow the viewport. Consider using full-width triggers (className="w-full") in narrow containers. The Command component handles touch scrolling within the list automatically. For very long lists, the CommandList component provides built-in scroll support.

Color & Contrast

The trigger button uses bg-background with border-input for consistent form styling. Selected items display a Check icon for clear visual feedback. The popover content inherits the card background to maintain contrast against the page in both light and dark modes.

Accessibility

Keyboard Navigation

Enter or Space — Open the combobox popover
Arrow Down / Arrow Up — Navigate through items in the list
Enter — Select the highlighted item
Escape — Close the popover and return focus to the trigger
Type-ahead search is supported: typing filters the list in real time

Screen Reader Support

The trigger button uses role="combobox" to announce its purpose
aria-expanded reflects whether the popover is open or closed
The Command component announces the number of matching results as the user types
Selected items are conveyed through visual check marks and ARIA selection state

Focus Management

When the popover opens, focus moves automatically to the CommandInput for immediate searching. When an item is selected or the popover is dismissed, focus returns to the trigger button. The visible focus ring uses focus-visible:ring-[3px] for clear keyboard navigation indication.

ARIA Attributes

{/* Trigger button with combobox role */}
<Button
  variant="outline"
  role="combobox"
  aria-expanded={open}
  aria-haspopup="listbox"
  aria-controls="framework-listbox"
>
  {selectedLabel || "Select framework..."}
  <ChevronsUpDown className="ml-2 h-4 w-4" />
</Button>

{/* Command list with listbox role */}
<Command>
  <CommandInput
    placeholder="Search framework..."
    aria-label="Search frameworks"
  />
  <CommandList id="framework-listbox" role="listbox">
    <CommandEmpty>No framework found.</CommandEmpty>
    <CommandGroup>
      <CommandItem role="option" aria-selected={isSelected}>
        {framework.label}
      </CommandItem>
    </CommandGroup>
  </CommandList>
</Command>

API Reference

The Combobox is a composition pattern using Popover and Command components. The following tables describe the key props for each part.

Combobox Pattern

Prop	Type	Default	Description
open	`boolean`	false	The controlled open state of the popover.
onOpenChange	`(open: boolean) => void`	—	Event handler called when the open state changes.
value	`string`	""	The controlled selected value.
onSelect	`(value: string) => void`	—	Event handler called when an item is selected from the list.

Command Components

Prop	Type	Default	Description
CommandInput	`component`	—	Search input for filtering items. Supports placeholder text.
CommandList	`component`	—	Scrollable container for command items.
CommandEmpty	`component`	—	Displayed when no items match the search query.
CommandGroup	`component`	—	Groups related command items together with an optional heading.
CommandItem	`component`	—	Individual selectable item. Accepts value and onSelect props.