ComboBox

A combo box combines a text input with a listbox, allowing users to filter a list of options to items matching a query.

Theme

Favorite Animal

label

selectionMode

isDisabled

Example

ComboBox.tsx

ComboBox.css

Example

ComboBox.tsx

ComboBox.css

import {ComboBox, ComboBoxItem} from './ComboBox';

<ComboBox
  label="Favorite Animal"
  placeholder="Select an animal">
  <ComboBoxItem>Aardvark</ComboBoxItem>
  <ComboBoxItem>Cat</ComboBoxItem>
  <ComboBoxItem>Dog</ComboBoxItem>
  <ComboBoxItem>Kangaroo</ComboBoxItem>
  <ComboBoxItem>Panda</ComboBoxItem>
  <ComboBoxItem>Snake</ComboBoxItem>
</ComboBox>

Autocomplete vs. ComboBox

Use ComboBox to select one or more values from a pre-defined set of options. Use Autocomplete to filter a collection or provide text completions.

Content

ComboBox reuses the ListBox component, following the Collection Components API. It supports ListBox features such as static and dynamic collections, sections, disabled items, links, text slots, asynchronous loading, etc. See the ListBox docs for more details.

The following example shows a dynamic collection of items, grouped into sections.

Preferred fruit or vegetable

import {ComboBox, ComboBoxItem} from './ComboBox';
import {ListBoxSection, Header} from './ListBox';
import {Collection} from 'react-aria-components/Collection';

function Example() {
    {name: 'Fruit', children: [
      {name: 'Apple'},
      {name: 'Banana'},
      {name: 'Orange'},
      {name: 'Honeydew'},
      {name: 'Grapes'},
      {name: 'Watermelon'},
      {name: 'Cantaloupe'},
      {name: 'Pear'}
    ]},
    {name: 'Vegetable', children: [
      {name: 'Cabbage'},
      {name: 'Broccoli'},
      {name: 'Carrots'},
      {name: 'Lettuce'},
      {name: 'Spinach'},
      {name: 'Bok Choy'},
      {name: 'Cauliflower'},
      {name: 'Potatoes'}
    ]}
  ];

  return (
    <ComboBox
      label="Preferred fruit or vegetable"
      placeholder="Select an option"
      defaultItems={options}>
      {section => (
        <ListBoxSection id={section.name}>
          <Header>{section.name}</Header>
          <Collection items={section.children}>
            {item => <ComboBoxItem id={item.name}>{item.name}</ComboBoxItem>}
          </Collection>
        </ListBoxSection>
      )}
    </ComboBox>
  );
}

Use the ComboBoxValue render prop function to display the selected items as a TagGroup.

States

import {ComboBox, ComboBoxValue, Input} from 'react-aria-components/ComboBox';
import {ComboBoxListBox, ComboBoxItem} from './ComboBox';
import {Label, FieldButton} from './Form';
import {Popover} from './Popover';
import {Tag, TagGroup} from './TagGroup';
import {ChevronDown} from 'lucide-react';

  {id: 'AL', name: 'Alabama'},
  {id: 'AK', name: 'Alaska'},
  {id: 'AZ', name: 'Arizona'},
  {id: 'AR', name: 'Arkansas'},
  {id: 'CA', name: 'California'},
  {id: 'CO', name: 'Colorado'},
  {id: 'CT', name: 'Connecticut'},
  {id: 'DE', name: 'Delaware'},
  {id: 'DC', name: 'District of Columbia'},
  {id: 'FL', name: 'Florida'},
  {id: 'GA', name: 'Georgia'},
  {id: 'HI', name: 'Hawaii'},
  {id: 'ID', name: 'Idaho'},
  {id: 'IL', name: 'Illinois'},
  {id: 'IN', name: 'Indiana'},
  {id: 'IA', name: 'Iowa'},
  {id: 'KS', name: 'Kansas'},
  {id: 'KY', name: 'Kentucky'},
  {id: 'LA', name: 'Louisiana'},
  {id: 'ME', name: 'Maine'},
  {id: 'MD', name: 'Maryland'},
  {id: 'MA', name: 'Massachusetts'},
  {id: 'MI', name: 'Michigan'},
  {id: 'MN', name: 'Minnesota'},
  {id: 'MS', name: 'Mississippi'},
  {id: 'MO', name: 'Missouri'},
  {id: 'MT', name: 'Montana'},
  {id: 'NE', name: 'Nebraska'},
  {id: 'NV', name: 'Nevada'},
  {id: 'NH', name: 'New Hampshire'},
  {id: 'NJ', name: 'New Jersey'},
  {id: 'NM', name: 'New Mexico'},
  {id: 'NY', name: 'New York'},
  {id: 'NC', name: 'North Carolina'},
  {id: 'ND', name: 'North Dakota'},
  {id: 'OH', name: 'Ohio'},
  {id: 'OK', name: 'Oklahoma'},
  {id: 'OR', name: 'Oregon'},
  {id: 'PA', name: 'Pennsylvania'},
  {id: 'RI', name: 'Rhode Island'},
  {id: 'SC', name: 'South Carolina'},
  {id: 'SD', name: 'South Dakota'},
  {id: 'TN', name: 'Tennessee'},
  {id: 'TX', name: 'Texas'},
  {id: 'UT', name: 'Utah'},
  {id: 'VT', name: 'Vermont'},
  {id: 'VA', name: 'Virginia'},
  {id: 'WA', name: 'Washington'},
  {id: 'WV', name: 'West Virginia'},
  {id: 'WI', name: 'Wisconsin'},
  {id: 'WY', name: 'Wyoming'}
];

<ComboBox selectionMode="multiple">
  <Label>States</Label>
  <div className="combobox-field">
    <Input className="react-aria-Input inset" placeholder="Select a state" />
    <FieldButton><ChevronDown /></FieldButton>
  </div>
  <ComboBoxValue<typeof states[0]>>
    {({selectedItems, state}) => (
      <TagGroup
        aria-label="Selected states"
        style={{marginTop: 8}}
        items={selectedItems.filter(item => item != null)}
        renderEmptyState={() => 'No selected items'}
        onRemove={(keys) => {
          // Remove keys from ComboBox state.
          if (Array.isArray(state.value)) {
            state.setValue(