ComboBox

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

Example#

import {Button, ComboBox, Input, Item, Label, ListBox, Popover} from 'react-aria-components';

<ComboBox>
  <Label>Favorite Animal</Label>
  <div>
    <Input />
    <Button>▼</Button>
  </div>
  <Popover>
    <ListBox>
      <Item>Aardvark</Item>
      <Item>Cat</Item>
      <Item>Dog</Item>
      <Item>Kangaroo</Item>
      <Item>Panda</Item>
      <Item>Snake</Item>
    </ListBox>
  </Popover>
</ComboBox>

import {
  Button,
  ComboBox,
  Input,
  Item,
  Label,
  ListBox,
  Popover
} from 'react-aria-components';

<ComboBox>
  <Label>Favorite Animal</Label>
  <div>
    <Input />
    <Button>▼</Button>
  </div>
  <Popover>
    <ListBox>
      <Item>Aardvark</Item>
      <Item>Cat</Item>
      <Item>Dog</Item>
      <Item>Kangaroo</Item>
      <Item>Panda</Item>
      <Item>Snake</Item>
    </ListBox>
  </Popover>
</ComboBox>

import {
  Button,
  ComboBox,
  Input,
  Item,
  Label,
  ListBox,
  Popover
} from 'react-aria-components';

<ComboBox>
  <Label>
    Favorite Animal
  </Label>
  <div>
    <Input />
    <Button>▼</Button>
  </div>
  <Popover>
    <ListBox>
      <Item>
        Aardvark
      </Item>
      <Item>Cat</Item>
      <Item>Dog</Item>
      <Item>
        Kangaroo
      </Item>
      <Item>
        Panda
      </Item>
      <Item>
        Snake
      </Item>
    </ListBox>
  </Popover>
</ComboBox>

.react-aria-ComboBox {
  & input {
    margin: 0;
    font-size: 1.072rem;
    border: 1px solid var(--spectrum-global-color-gray-400);
    border-radius: 6px;
    padding: 4px 2rem 4px 8px;
    vertical-align: middle;

    &[aria-invalid] {
      border-color: var(--spectrum-global-color-red-600);
    }

    &:focus {
      outline: none;
      border-color: slateblue;
      box-shadow: 0 0 0 1px slateblue;
    }
  }

  & button {
    background: slateblue;
    color: white;
    border-radius: 4px;
    border: none;
    appearance: none;
    margin-left: -1.714rem;
    width: 1.429rem;
    height: 1.429rem;
    padding: 0;
    vertical-align: middle;
    font-size: 0.857rem;
    outline: none;
  }

  & [slot=description] {
    font-size: 12px;
  }

  & [slot=errorMessage] {
    font-size: 12px;
    color: var(--spectrum-global-color-red-600);
  }
}

.react-aria-ListBox {
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--spectrum-global-color-gray-400);
  box-shadow: 0 8px 20px rgba(0 0 0 / 0.1);
  border-radius: 6px;
  background: var(--page-background);
  width: var(--combobox-width);
  box-sizing: border-box;

  & section:not(:first-child) {
    margin-top: 12px;
  }

  & section header {
    font-size: 16px;
    font-weight: bold;
    padding: 0 8px 0 22px;
  }

  & .react-aria-Item {
    margin: 2px;
    padding: 4px 8px 4px 22px;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--spectrum-global-color-gray-800);
    font-size: 1.072rem;
    position: relative;
    display: flex;
    flex-direction: column;

    &[aria-selected=true] {
      font-weight: 600;

      &::before {
        content: '✓';
        content: '✓' / '';
        alt: ' ';
        position: absolute;
        top: 4px;
        left: 4px;
      }
    }

    &[data-focused],
    &[data-pressed] {
      background: slateblue;
      color: white;
    }

    &[aria-disabled] {
      opacity: 0.4;
    }

    & [slot=label] {
      font-weight: bold;
    }

    & [slot=description] {
      font-size: small;
    }
  }
}

.react-aria-ComboBox {
  & input {
    margin: 0;
    font-size: 1.072rem;
    border: 1px solid var(--spectrum-global-color-gray-400);
    border-radius: 6px;
    padding: 4px 2rem 4px 8px;
    vertical-align: middle;

    &[aria-invalid] {
      border-color: var(--spectrum-global-color-red-600);
    }

    &:focus {
      outline: none;
      border-color: slateblue;
      box-shadow: 0 0 0 1px slateblue;
    }
  }

  & button {
    background: slateblue;
    color: white;
    border-radius: 4px;
    border: none;
    appearance: none;
    margin-left: -1.714rem;
    width: 1.429rem;
    height: 1.429rem;
    padding: 0;
    vertical-align: middle;
    font-size: 0.857rem;
    outline: none;
  }

  & [slot=description] {
    font-size: 12px;
  }

  & [slot=errorMessage] {
    font-size: 12px;
    color: var(--spectrum-global-color-red-600);
  }
}

.react-aria-ListBox {
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--spectrum-global-color-gray-400);
  box-shadow: 0 8px 20px rgba(0 0 0 / 0.1);
  border-radius: 6px;
  background: var(--page-background);
  width: var(--combobox-width);
  box-sizing: border-box;

  & section:not(:first-child) {
    margin-top: 12px;
  }

  & section header {
    font-size: 16px;
    font-weight: bold;
    padding: 0 8px 0 22px;
  }

  & .react-aria-Item {
    margin: 2px;
    padding: 4px 8px 4px 22px;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--spectrum-global-color-gray-800);
    font-size: 1.072rem;
    position: relative;
    display: flex;
    flex-direction: column;

    &[aria-selected=true] {
      font-weight: 600;

      &::before {
        content: '✓';
        content: '✓' / '';
        alt: ' ';
        position: absolute;
        top: 4px;
        left: 4px;
      }
    }

    &[data-focused],
    &[data-pressed] {
      background: slateblue;
      color: white;
    }

    &[aria-disabled] {
      opacity: 0.4;
    }

    & [slot=label] {
      font-weight: bold;
    }

    & [slot=description] {
      font-size: small;
    }
  }
}

.react-aria-ComboBox {
  & input {
    margin: 0;
    font-size: 1.072rem;
    border: 1px solid var(--spectrum-global-color-gray-400);
    border-radius: 6px;
    padding: 4px 2rem 4px 8px;
    vertical-align: middle;

    &[aria-invalid] {
      border-color: var(--spectrum-global-color-red-600);
    }

    &:focus {
      outline: none;
      border-color: slateblue;
      box-shadow: 0 0 0 1px slateblue;
    }
  }

  & button {
    background: slateblue;
    color: white;
    border-radius: 4px;
    border: none;
    appearance: none;
    margin-left: -1.714rem;
    width: 1.429rem;
    height: 1.429rem;
    padding: 0;
    vertical-align: middle;
    font-size: 0.857rem;
    outline: none;
  }

  & [slot=description] {
    font-size: 12px;
  }

  & [slot=errorMessage] {
    font-size: 12px;
    color: var(--spectrum-global-color-red-600);
  }
}

.react-aria-ListBox {
  max-height: inherit;
  overflow: auto;
  padding: 2px;
  border: 1px solid var(--spectrum-global-color-gray-400);
  box-shadow: 0 8px 20px rgba(0 0 0 / 0.1);
  border-radius: 6px;
  background: var(--page-background);
  width: var(--combobox-width);
  box-sizing: border-box;

  & section:not(:first-child) {
    margin-top: 12px;
  }

  & section header {
    font-size: 16px;
    font-weight: bold;
    padding: 0 8px 0 22px;
  }

  & .react-aria-Item {
    margin: 2px;
    padding: 4px 8px 4px 22px;
    border-radius: 6px;
    outline: none;
    cursor: default;
    color: var(--spectrum-global-color-gray-800);
    font-size: 1.072rem;
    position: relative;
    display: flex;
    flex-direction: column;

    &[aria-selected=true] {
      font-weight: 600;

      &::before {
        content: '✓';
        content: '✓' / '';
        alt: ' ';
        position: absolute;
        top: 4px;
        left: 4px;
      }
    }

    &[data-focused],
    &[data-pressed] {
      background: slateblue;
      color: white;
    }

    &[aria-disabled] {
      opacity: 0.4;
    }

    & [slot=label] {
      font-weight: bold;
    }

    & [slot=description] {
      font-size: small;
    }
  }
}

Features#

A combo box can be built using the <datalist> HTML element, but this is very limited in functionality and difficult to style. ComboBox helps achieve accessible combo box and autocomplete components that can be styled as needed.

• Flexible – Support for selecting pre-defined values, custom values, controlled and uncontrolled state, custom filter functions, async loading, disabled items, validation, and multiple menu trigger options.
• Keyboard navigation – ComboBox can be opened and navigated using the arrow keys, along with page up/down, home/end, etc. The list of options is filtered while typing into the input, and items can be selected with the enter key.
• Accessible – Follows the ARIA combobox pattern, with support for items and sections, and slots for label and description elements within each item. Custom localized announcements are included for option focusing, filtering, and selection using an ARIA live region to ensure announcements are clear and consistent.
• Styleable – Items include builtin states for styling, such as hover, press, focus, selected, and disabled.

Read our blog post for more details about the interactions and accessibility features implemented by ComboBox.

Anatomy#

A combo box consists of a label, an input which displays the current value, a list box popup, and an optional button used to toggle the list box popup open state. Users can type within the input to filter the available options within the list box. The list box popup may be opened by a variety of input field interactions specified by the menuTrigger prop provided to ComboBox, or by clicking or touching the button.

ComboBox also supports optional description and error message elements, which can be used to provide more context about the field, and any validation messages. These are linked with the input via the aria-describedby attribute.

If the combo box does not have a visible label, an aria-label or aria-labelledby prop must be passed instead to identify it to assistive technology.

Concepts#

ComboBox makes use of the following concepts:

• Collections
• Selection

Composed components#

A ComboBox uses the following components, which may also be used standalone or reused in other components.

Props#

ComboBox#

Label#

A <Label> accepts all props supported by the <label> HTML element.

Input#

An <Input> accepts all props supported by the <input> HTML element.

Button#

A <Button> accepts its contents as children. Other props such as onPress and isDisabled will be set by the ComboBox.

Popover#

A <Popover> is a container to hold the <ListBox> suggestions for a ComboBox. By default, it has a placement of bottom start within a <ComboBox>, but this and other positioning properties may be customized.

ListBox#

Within a <ComboBox>, most <ListBox> props are set automatically. The <ListBox> defines the options to display in a ComboBox.

Section#

A <Section> defines the child items, and optional title for a section within a <ListBox>.

Item#

An <Item> defines a single option within a <ListBox>. If the children are not plain text, then the textValue prop must also be set to a plain text representation, which will be used for autocomplete in the ComboBox.

Styling#

React Aria components can be styled in many ways, including using CSS classes, inline styles, utility classes (e.g. Tailwind), CSS-in-JS (e.g. Styled Components), etc. By default, all components include a builtin className attribute which can be targeted using CSS selectors. These follow the react-aria-ComponentName naming convention.

.react-aria-ComboBox {
  /* ... */
}

.react-aria-ComboBox {
  /* ... */
}

.react-aria-ComboBox {
  /* ... */
}

A custom className can also be specified on any component. This overrides the default className provided by React Aria with your own.

<ComboBox className="my-combobox">
  {/* ... */}
</ComboBox>

<ComboBox className="my-combobox">
  {/* ... */}
</ComboBox>

<ComboBox className="my-combobox">
  {/* ... */}
</ComboBox>;

In addition, some components support multiple UI states (e.g. pressed, hovered, etc.). React Aria components expose states using DOM attributes, which you can target in CSS selectors. These are ARIA attributes wherever possible, or data attributes when a relevant ARIA attribute does not exist. For example:

.react-aria-Item[aria-selected=true] {
  /* ... */
}

.react-aria-Item[data-focused] {
  /* ... */
}

.react-aria-Item[aria-selected=true] {
  /* ... */
}

.react-aria-Item[data-focused] {
  /* ... */
}

.react-aria-Item[aria-selected=true] {
  /* ... */
}

.react-aria-Item[data-focused] {
  /* ... */
}

The className and style props also accept functions which receive states for styling. This lets you dynamically determine the classes or styles to apply, which is useful when using utility CSS libraries like Tailwind.

<Item className={({isSelected}) => isSelected ? 'bg-blue-400' : 'bg-gray-100'}>
  Item
</Item>

<Item
  className={({ isSelected }) =>
    isSelected ? 'bg-blue-400' : 'bg-gray-100'}
>
  Item
</Item>;

<Item
  className={(
    { isSelected }
  ) =>
    isSelected
      ? 'bg-blue-400'
      : 'bg-gray-100'}
>
  Item
</Item>;

Render props may also be used as children to alter what elements are rendered based on the current state. For example, you could render a checkmark icon when an item is selected.

<Item>
  {({isSelected}) => (
    <>
      {isSelected && <CheckmarkIcon />}
      Item
    </>
  )}
</Item>

<Item>
  {({isSelected}) => (
    <>
      {isSelected && <CheckmarkIcon />}
      Item
    </>
  )}
</Item>

<Item>
  {({ isSelected }) => (
    <>
      {isSelected && (
        <CheckmarkIcon />
      )}
      Item
    </>
  )}
</Item>;

The states and selectors for each component used in a ComboBox are documented below.

ComboBox#

A ComboBox can be targeted with the .react-aria-ComboBox CSS selector, or by overriding with a custom className. It provides a ComboBoxState object to its render props, which can be used to customize the className, style, or children.

Label#

A Label can be targeted with the .react-aria-Label CSS selector, or by overriding with a custom className.

Input#

An Input within a ComboBox can be targeted with the input CSS selector, or by adding a custom className. It supports standard CSS pseudo classes such as :focus for states. See MDN for details.

Button#

A Button can be targeted with the button CSS selector, or by adding a custom className. It supports the following states:

Popover#

The Popover component can be targeted with the .react-aria-Popover CSS selector, or by overriding with a custom className. Note that it renders in a React Portal, so it will not appear as a descendant of the ComboBox in the DOM.

The --combobox-width CSS custom property will be set on the popover, which you can use to make the popover match the width of the combobox.

.react-aria-Popover {
  width: var(--combobox-width);
}

.react-aria-Popover {
  width: var(--combobox-width);
}

.react-aria-Popover {
  width: var(--combobox-width);
}

ListBox#

A ListBox can be targeted with the .react-aria-ListBox CSS selector, or by overriding with a custom className.

Section#

A Section can be targeted with the .react-aria-Section CSS selector, or by overriding with a custom className. The section title can be targeted with the header selector. The title prop also allows JSX elements and not just strings, which can enable custom formatting. However, keep in mind that interactive elements within a listbox are not allowed. See sections for examples.

Item#

An Item can be targeted with the .react-aria-Item CSS selector, or by overriding with a custom className. It supports the following states and render props:

Items also support two slots: a label, and a description. When provided using the <Text> element, the item will have aria-labelledby and aria-describedby attributes pointing to these slots, improving screen reader announcement. See complex items for an example.

Note that items may not contain interactive children such as buttons, as screen readers will not be able to access them.

Text#

The help text elements within a ComboBox can be targeted with the [slot=description] and [slot=errorMessage] CSS selectors, or by adding a custom className.

Reusable wrappers#

If you will use a ComboBox in multiple places in your app, you can wrap all of the pieces into a reusable component. This way, the DOM structure, styling code, and other logic are defined in a single place and reused everywhere to ensure consistency.

This example wraps ComboBox and all of its children together into a single component which accepts a label prop and children, which are passed through to the right places. It also shows how to use the description and errorMessage slots to render help text (see below for details). The Item component is also wrapped to apply class names based on the current state, as described above.

import {Text} from 'react-aria-components';

function MyComboBox({ label, description, errorMessage, children, ...props }) {
  return (
    <ComboBox {...props}>
      <Label>{label}</Label>
      <div className="my-combobox-container">
        <Input />
        <Button>▼</Button>
      </div>
      {description && <Text slot="description">{description}</Text>}
      {errorMessage && <Text slot="errorMessage">{errorMessage}</Text>}
      <Popover>
        <ListBox>
          {children}
        </ListBox>
      </Popover>
    </ComboBox>
  );
}

function MyItem(props) {
  return (
    <Item
      {...props}
      className={({ isFocused, isSelected }) =>
        `my-item ${isFocused ? 'focused' : ''} ${isSelected ? 'selected' : ''}`}
    />
  );
}

<MyComboBox label="Ice cream flavor">
  <MyItem>Chocolate</MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>Strawberry</MyItem>
  <MyItem>Vanilla</MyItem>
</MyComboBox>

import {Text} from 'react-aria-components';

function MyComboBox(
  { label, description, errorMessage, children, ...props }
) {
  return (
    <ComboBox {...props}>
      <Label>{label}</Label>
      <div className="my-combobox-container">
        <Input />
        <Button>▼</Button>
      </div>
      {description && (
        <Text slot="description">{description}</Text>
      )}
      {errorMessage && (
        <Text slot="errorMessage">{errorMessage}</Text>
      )}
      <Popover>
        <ListBox>
          {children}
        </ListBox>
      </Popover>
    </ComboBox>
  );
}

function MyItem(props) {
  return (
    <Item
      {...props}
      className={({ isFocused, isSelected }) =>
        `my-item ${isFocused ? 'focused' : ''} ${
          isSelected ? 'selected' : ''
        }`}
    />
  );
}

<MyComboBox label="Ice cream flavor">
  <MyItem>Chocolate</MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>Strawberry</MyItem>
  <MyItem>Vanilla</MyItem>
</MyComboBox>

import {Text} from 'react-aria-components';

function MyComboBox(
  {
    label,
    description,
    errorMessage,
    children,
    ...props
  }
) {
  return (
    <ComboBox {...props}>
      <Label>
        {label}
      </Label>
      <div className="my-combobox-container">
        <Input />
        <Button>
          ▼
        </Button>
      </div>
      {description && (
        <Text slot="description">
          {description}
        </Text>
      )}
      {errorMessage && (
        <Text slot="errorMessage">
          {errorMessage}
        </Text>
      )}
      <Popover>
        <ListBox>
          {children}
        </ListBox>
      </Popover>
    </ComboBox>
  );
}

function MyItem(props) {
  return (
    <Item
      {...props}
      className={(
        {
          isFocused,
          isSelected
        }
      ) =>
        `my-item ${
          isFocused
            ? 'focused'
            : ''
        } ${
          isSelected
            ? 'selected'
            : ''
        }`}
    />
  );
}

<MyComboBox label="Ice cream flavor">
  <MyItem>
    Chocolate
  </MyItem>
  <MyItem>Mint</MyItem>
  <MyItem>
    Strawberry
  </MyItem>
  <MyItem>
    Vanilla
  </MyItem>
</MyComboBox>

.my-item {
  margin: 2px;
  padding: 4px 8px 4px 22px;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--spectrum-global-color-gray-800);
  font-size: 1.072rem;
  position: relative;

  &.selected {
    font-weight: 600;

    &::before {
      content: '✓';
      content: '✓' / '';
      alt: ' ';
      position: absolute;
      top: 4px;
      left: 4px;
    }
  }

  &.focused {
    background: #e70073;
    color: white;
  }
}

.my-item {
  margin: 2px;
  padding: 4px 8px 4px 22px;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--spectrum-global-color-gray-800);
  font-size: 1.072rem;
  position: relative;

  &.selected {
    font-weight: 600;

    &::before {
      content: '✓';
      content: '✓' / '';
      alt: ' ';
      position: absolute;
      top: 4px;
      left: 4px;
    }
  }

  &.focused {
    background: #e70073;
    color: white;
  }
}

.my-item {
  margin: 2px;
  padding: 4px 8px 4px 22px;
  border-radius: 6px;
  outline: none;
  cursor: default;
  color: var(--spectrum-global-color-gray-800);
  font-size: 1.072rem;
  position: relative;

  &.selected {
    font-weight: 600;

    &::before {
      content: '✓';
      content: '✓' / '';
      alt: ' ';
      position: absolute;
      top: 4px;
      left: 4px;
    }
  }

  &.focused {
    background: #e70073;
    color: white;
  }
}

Usage#

The following examples show how to use the MyComboBox component created in the above example.

Dynamic collections#

ComboBox follows the Collection Components API, accepting both static and dynamic collections. The examples above show static collections, which can be used when the full list of options is known ahead of time. Dynamic collections, as shown below, can be used when the options come from an external data source such as an API call, or update over time.

As seen below, an iterable list of options is passed to the ComboBox using the defaultItems prop. Each item accepts an id prop, which is passed to the onSelectionChange handler to identify the selected item. Alternatively, if the item objects contain an id property, as shown in the example below, then this is used automatically and an id prop is not required.

function Example() {
  let options = [
    {id: 1, name: 'Aerospace'},
    {id: 2, name: 'Mechanical'},
    {id: 3, name: 'Civil'},
    {id: 4, name: 'Biomedical'},
    {id: 5, name: 'Nuclear'},
    {id: 6, name: 'Industrial'},
    {id: 7, name: 'Chemical'},
    {id: 8, name: 'Agricultural'},
    {id: 9, name: 'Electrical'}
  ];
  let [majorId, setMajorId] = React.useState();

  return (
    <>
      <MyComboBox defaultItems={options} onSelectionChange={setMajorId}>
        {(item) => <Item>{item.name}</Item>}
      </MyComboBox>
      <p>Selected topic id: {majorId}</p>
    </>
  );
}

function Example() {
  let options = [
    { id: 1, name: 'Aerospace' },
    { id: 2, name: 'Mechanical' },
    { id: 3, name: 'Civil' },
    { id: 4, name: 'Biomedical' },
    { id: 5, name: 'Nuclear' },
    { id: 6, name: 'Industrial' },
    { id: 7, name: 'Chemical' },
    { id: 8, name: 'Agricultural' },
    { id: 9, name: 'Electrical' }
  ];
  let [majorId, setMajorId] = React.useState();

  return (
    <>
      <MyComboBox
        defaultItems={options}
        onSelectionChange={setMajorId}
      >
        {(item) => <Item>{item.name}</Item>}
      </MyComboBox>
      <p>Selected topic id: {majorId}</p>
    </>
  );
}

function Example() {
  let options = [
    {
      id: 1,
      name: 'Aerospace'
    },
    {
      id: 2,
      name: 'Mechanical'
    },
    {
      id: 3,
      name: 'Civil'
    },
    {
      id: 4,
      name: 'Biomedical'
    },
    {
      id: 5,
      name: 'Nuclear'
    },
    {
      id: 6,
      name: 'Industrial'
    },
    {
      id: 7,
      name: 'Chemical'
    },
    {
      id: 8,
      name:
        'Agricultural'
    },
    {
      id: 9,
      name: 'Electrical'
    }
  ];
  let [
    majorId,
    setMajorId
  ] = React.useState();

  return (
    <>
      <MyComboBox
        defaultItems={options}
        onSelectionChange={setMajorId}
      >
        {(item) => (
          <Item>
            {item.name}
          </Item>
        )}
      </MyComboBox>
      <p>
        Selected topic
        id: {majorId}
      </p>
    </>
  );
}

Allow custom values#

By default, ComboBox doesn't allow users to specify a value that doesn't exist in the list of options and will revert the input value to the current selected value on blur. By specifying allowsCustomValue, this behavior is suppressed and the user is free to enter any value within the field.

<MyComboBox label="Favorite Animal" allowsCustomValue>
  <Item id="red panda">Red Panda</Item>
  <Item id="cat">Cat</Item>
  <Item id="dog">Dog</Item>
  <Item id="aardvark">Aardvark</Item>
  <Item id="kangaroo">Kangaroo</Item>
  <Item id="snake">Snake</Item>
</MyComboBox>

<MyComboBox label="Favorite Animal" allowsCustomValue>
  <Item id="red panda">Red Panda</Item>
  <Item id="cat">Cat</Item>
  <Item id="dog">Dog</Item>
  <Item id="aardvark">Aardvark</Item>
  <Item id="kangaroo">Kangaroo</Item>
  <Item id="snake">Snake</Item>
</MyComboBox>

<MyComboBox
  label="Favorite Animal"
  allowsCustomValue
>
  <Item id="red panda">
    Red Panda
  </Item>
  <Item id="cat">
    Cat
  </Item>
  <Item id="dog">
    Dog
  </Item>
  <Item id="aardvark">
    Aardvark
  </Item>
  <Item id="kangaroo">
    Kangaroo
  </Item>
  <Item id="snake">
    Snake
  </Item>
</MyComboBox>

Sections#

ComboBox supports sections in order to group options. Sections can be used by wrapping groups of items in a Section element. Each Section takes a title prop.

Static items

import {Section} from 'react-aria-components';

<MyComboBox label="Preferred fruit or vegetable">
  <Section title="Fruit">
    <Item id="Apple">Apple</Item>
    <Item id="Banana">Banana</Item>
    <Item id="Orange">Orange</Item>
    <Item id="Honeydew">Honeydew</Item>
    <Item id="Grapes">Grapes</Item>
    <Item id="Watermelon">Watermelon</Item>
    <Item id="Cantaloupe">Cantaloupe</Item>
    <Item id="Pear">Pear</Item>
  </Section>
  <Section title="Vegetable">
    <Item id="Cabbage">Cabbage</Item>
    <Item id="Broccoli">Broccoli</Item>
    <Item id="Carrots">Carrots</Item>
    <Item id="Lettuce">Lettuce</Item>
    <Item id="Spinach">Spinach</Item>
    <Item id="Bok Choy">Bok Choy</Item>
    <Item id="Cauliflower">Cauliflower</Item>
    <Item id="Potatoes">Potatoes</Item>
  </Section>
</MyComboBox>

import {Section} from 'react-aria-components';

<MyComboBox label="Preferred fruit or vegetable">
  <Section title="Fruit">
    <Item id="Apple">Apple</Item>
    <Item id="Banana">Banana</Item>
    <Item id="Orange">Orange</Item>
    <Item id="Honeydew">Honeydew</Item>
    <Item id="Grapes">Grapes</Item>
    <Item id="Watermelon">Watermelon</Item>
    <Item id="Cantaloupe">Cantaloupe</Item>
    <Item id="Pear">Pear</Item>
  </Section>
  <Section title="Vegetable">
    <Item id="Cabbage">Cabbage</Item>
    <Item id="Broccoli">Broccoli</Item>
    <Item id="Carrots">Carrots</Item>
    <Item id="Lettuce">Lettuce</Item>
    <Item id="Spinach">Spinach</Item>
    <Item id="Bok Choy">Bok Choy</Item>
    <Item id="Cauliflower">Cauliflower</Item>
    <Item id="Potatoes">Potatoes</Item>
  </Section>
</MyComboBox>

import {Section} from 'react-aria-components';

<MyComboBox label="Preferred fruit or vegetable">
  <Section title="Fruit">
    <Item id="Apple">
      Apple
    </Item>
    <Item id="Banana">
      Banana
    </Item>
    <Item id="Orange">
      Orange
    </Item>
    <Item id="Honeydew">
      Honeydew
    </Item>
    <Item id="Grapes">
      Grapes
    </Item>
    <Item id="Watermelon">
      Watermelon
    </Item>
    <Item id="Cantaloupe">
      Cantaloupe
    </Item>
    <Item id="Pear">
      Pear
    </Item>
  </Section>
  <Section title="Vegetable">
    <Item id="Cabbage">
      Cabbage
    </Item>
    <Item id="Broccoli">
      Broccoli
    </Item>
    <Item id="Carrots">
      Carrots
    </Item>
    <Item id="Lettuce">
      Lettuce
    </Item>
    <Item id="Spinach">
      Spinach
    </Item>
    <Item id="Bok Choy">
      Bok Choy
    </Item>
    <Item id="Cauliflower">
      Cauliflower
    </Item>
    <Item id="Potatoes">
      Potatoes
    </Item>
  </Section>
</MyComboBox>

Dynamic items

Sections used with dynamic items are populated from a hierarchical data structure. Please note that Section takes an array of data using the items prop only.

function Example() {
  let options = [
    {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 (
    <MyComboBox label="Preferred fruit or vegetable" defaultItems={options}>
      {item => (
        <Section id={item.name} items={item.children} title={item.name}>
          {item => <Item id={item.name}>{item.name}</Item>}
        </Section>
      )}
    </MyComboBox>
  );
}

function Example() {
  let options = [
    {
      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 (
    <MyComboBox
      label="Preferred fruit or vegetable"
      defaultItems={options}
    >
      {(item) => (
        <Section
          id={item.name}
          items={item.children}
          title={item.name}
        >
          {(item) => <Item id={item.name}>{item.name}
          </Item>}
        </Section>
      )}
    </MyComboBox>
  );
}

function Example() {
  let options = [
    {
      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 (
    <MyComboBox
      label="Preferred fruit or vegetable"
      defaultItems={options}
    >
      {(item) => (
        <Section
          id={item.name}
          items={item
            .children}
          title={item
            .name}
        >
          {(item) => (
            <Item
              id={item
                .name}
            >
              {item.name}
            </Item>
          )}
        </Section>
      )}
    </MyComboBox>
  );
}

Complex items#

Items within ComboBox also allow for additional content used to better communicate options. Icons and descriptions can be added to the children of Item as shown in the example below. If a description is added, the prop slot="description" must be used to distinguish the different <Text> elements.

import {Text} from 'react-aria-components';

<MyComboBox label="Select action">
  <Item textValue="Add to queue">
    <Text slot="label">Add to queue</Text>
    <Text slot="description">Add to current watch queue.</Text>
  </Item>
  <Item textValue="Add review">
    <Text slot="label">Add review</Text>
    <Text slot="description">Post a review for the episode.</Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Text slot="label">Subscribe to series</Text>
    <Text slot="description">
      Add series to your subscription list and be notified when a new episode
      airs.
    </Text>
  </Item>
  <Item textValue="Report">
    <Text slot="label">Report</Text>
    <Text slot="description">Report an issue/violation.</Text>
  </Item>
</MyComboBox>

import {Text} from 'react-aria-components';

<MyComboBox label="Select action">
  <Item textValue="Add to queue">
    <Text slot="label">Add to queue</Text>
    <Text slot="description">
      Add to current watch queue.
    </Text>
  </Item>
  <Item textValue="Add review">
    <Text slot="label">Add review</Text>
    <Text slot="description">
      Post a review for the episode.
    </Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Text slot="label">Subscribe to series</Text>
    <Text slot="description">
      Add series to your subscription list and be notified
      when a new episode airs.
    </Text>
  </Item>
  <Item textValue="Report">
    <Text slot="label">Report</Text>
    <Text slot="description">
      Report an issue/violation.
    </Text>
  </Item>
</MyComboBox>

import {Text} from 'react-aria-components';

<MyComboBox label="Select action">
  <Item textValue="Add to queue">
    <Text slot="label">
      Add to queue
    </Text>
    <Text slot="description">
      Add to current
      watch queue.
    </Text>
  </Item>
  <Item textValue="Add review">
    <Text slot="label">
      Add review
    </Text>
    <Text slot="description">
      Post a review for
      the episode.
    </Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Text slot="label">
      Subscribe to
      series
    </Text>
    <Text slot="description">
      Add series to
      your subscription
      list and be
      notified when a
      new episode airs.
    </Text>
  </Item>
  <Item textValue="Report">
    <Text slot="label">
      Report
    </Text>
    <Text slot="description">
      Report an
      issue/violation.
    </Text>
  </Item>
</MyComboBox>

Custom filtering#

By default, ComboBox uses a "contains" function from useFilter to filter the list of options. This can be overridden using the defaultFilter prop, or by using the items prop to control the filtered list. When items is provided rather than defaultItems, ComboBox does no filtering of its own.

The following example makes the inputValue controlled, and updates the filtered list that is passed to the items prop when the input changes value.

import {useFilter} from 'react-aria';

function Example() {
  let options = [
    { id: 1, email: 'fake@email.com' },
    { id: 2, email: 'anotherfake@email.com' },
    { id: 3, email: 'bob@email.com' },
    { id: 4, email: 'joe@email.com' },
    { id: 5, email: 'yourEmail@email.com' },
    { id: 6, email: 'valid@email.com' },
    { id: 7, email: 'spam@email.com' },
    { id: 8, email: 'newsletter@email.com' },
    { id: 9, email: 'subscribe@email.com' }
  ];

  let { startsWith } = useFilter({ sensitivity: 'base' });
  let [filterValue, setFilterValue] = React.useState('');
  let filteredItems = React.useMemo(
    () => options.filter((item) => startsWith(item.email, filterValue)),
    [options, filterValue]
  );

  return (
    <MyComboBox
      label="To:"
      items={filteredItems}
      inputValue={filterValue}
      onInputChange={setFilterValue}
      allowsCustomValue
    >
      {(item) => <Item>{item.email}</Item>}
    </MyComboBox>
  );
}

import {useFilter} from 'react-aria';

function Example() {
  let options = [
    { id: 1, email: 'fake@email.com' },
    { id: 2, email: 'anotherfake@email.com' },
    { id: 3, email: 'bob@email.com' },
    { id: 4, email: 'joe@email.com' },
    { id: 5, email: 'yourEmail@email.com' },
    { id: 6, email: 'valid@email.com' },
    { id: 7, email: 'spam@email.com' },
    { id: 8, email: 'newsletter@email.com' },
    { id: 9, email: 'subscribe@email.com' }
  ];

  let { startsWith } = useFilter({ sensitivity: 'base' });
  let [filterValue, setFilterValue] = React.useState('');
  let filteredItems = React.useMemo(
    () =>
      options.filter((item) =>
        startsWith(item.email, filterValue)
      ),
    [options, filterValue]
  );

  return (
    <MyComboBox
      label="To:"
      items={filteredItems}
      inputValue={filterValue}
      onInputChange={setFilterValue}
      allowsCustomValue
    >
      {(item) => <Item>{item.email}</Item>}
    </MyComboBox>
  );
}

import {useFilter} from 'react-aria';

function Example() {
  let options = [
    {
      id: 1,
      email:
        'fake@email.com'
    },
    {
      id: 2,
      email:
        'anotherfake@email.com'
    },
    {
      id: 3,
      email:
        'bob@email.com'
    },
    {
      id: 4,
      email:
        'joe@email.com'
    },
    {
      id: 5,
      email:
        'yourEmail@email.com'
    },
    {
      id: 6,
      email:
        'valid@email.com'
    },
    {
      id: 7,
      email:
        'spam@email.com'
    },
    {
      id: 8,
      email:
        'newsletter@email.com'
    },
    {
      id: 9,
      email:
        'subscribe@email.com'
    }
  ];

  let { startsWith } =
    useFilter({
      sensitivity: 'base'
    });
  let [
    filterValue,
    setFilterValue
  ] = React.useState('');
  let filteredItems =
    React.useMemo(
      () =>
        options.filter((
          item
        ) =>
          startsWith(
            item.email,
            filterValue
          )
        ),
      [
        options,
        filterValue
      ]
    );

  return (
    <MyComboBox
      label="To:"
      items={filteredItems}
      inputValue={filterValue}
      onInputChange={setFilterValue}
      allowsCustomValue
    >
      {(item) => (
        <Item>
          {item.email}
        </Item>
      )}
    </MyComboBox>
  );
}

Fully controlled#

The following example shows how you would create a controlled ComboBox, controlling everything from the selected value (selectedKey) to the combobox options (items). By passing in inputValue, selectedKey, and items to the ComboBox you can control exactly what your ComboBox should display. For example, note that the item filtering for the controlled ComboBox below now follows a "starts with" filter strategy, accomplished by controlling the exact set of items available to the ComboBox whenever the input value updates.

It is important to note that you don't have to control every single aspect of a ComboBox. If you decide to only control a single property of the ComboBox, be sure to provide the change handler for that prop as well e.g. controlling selectedKey would require onSelectionChange to be passed to ComboBox as well.

function ControlledComboBox() {
  let optionList = [
    { name: 'Red Panda', id: '1' },
    { name: 'Cat', id: '2' },
    { name: 'Dog', id: '3' },
    { name: 'Aardvark', id: '4' },
    { name: 'Kangaroo', id: '5' },
    { name: 'Snake', id: '6' }
  ];

  // Store ComboBox input value, selected option, open state, and items
  // in a state tracker
  let [fieldState, setFieldState] = React.useState({
    selectedKey: '',
    inputValue: '',
    items: optionList
  });

  // Implement custom filtering logic and control what items are
  // available to the ComboBox.
  let { startsWith } = useFilter({ sensitivity: 'base' });

  // Specify how each of the ComboBox values should change when an
  // option is selected from the list box
  let onSelectionChange = (key) => {
    setFieldState((prevState) => {
      let selectedItem = prevState.items.find((option) => option.id === key);
      return ({
        inputValue: selectedItem?.name ?? '',
        selectedKey: key,
        items: optionList.filter((item) =>
          startsWith(item.name, selectedItem?.name ?? '')
        )
      });
    });
  };

  // Specify how each of the ComboBox values should change when the input
  // field is altered by the user
  let onInputChange = (value) => {
    setFieldState((prevState) => ({
      inputValue: value,
      selectedKey: value === '' ? null : prevState.selectedKey,
      items: optionList.filter((item) => startsWith(item.name, value))
    }));
  };

  // Show entire list if user opens the menu manually
  let onOpenChange = (isOpen, menuTrigger) => {
    if (menuTrigger === 'manual' && isOpen) {
      setFieldState((prevState) => ({
        inputValue: prevState.inputValue,
        selectedKey: prevState.selectedKey,
        items: optionList
      }));
    }
  };

  // Pass each controlled prop to ComboBox along with their
  // change handlers
  return (
    <MyComboBox
      label="Favorite Animal"
      items={fieldState.items}
      selectedKey={fieldState.selectedKey}
      inputValue={fieldState.inputValue}
      onOpenChange={onOpenChange}
      onSelectionChange={onSelectionChange}
      onInputChange={onInputChange}
    >
      {(item) => <Item>{item.name}</Item>}
    </MyComboBox>
  );
}

<ControlledComboBox />

function ControlledComboBox() {
  let optionList = [
    { name: 'Red Panda', id: '1' },
    { name: 'Cat', id: '2' },
    { name: 'Dog', id: '3' },
    { name: 'Aardvark', id: '4' },
    { name: 'Kangaroo', id: '5' },
    { name: 'Snake', id: '6' }
  ];

  // Store ComboBox input value, selected option, open state, and items
  // in a state tracker
  let [fieldState, setFieldState] = React.useState({
    selectedKey: '',
    inputValue: '',
    items: optionList
  });

  // Implement custom filtering logic and control what items are
  // available to the ComboBox.
  let { startsWith } = useFilter({ sensitivity: 'base' });

  // Specify how each of the ComboBox values should change when an
  // option is selected from the list box
  let onSelectionChange = (key) => {
    setFieldState((prevState) => {
      let selectedItem = prevState.items.find((option) =>
        option.id === key
      );
      return ({
        inputValue: selectedItem?.name ?? '',
        selectedKey: key,
        items: optionList.filter((item) =>
          startsWith(item.name, selectedItem?.name ?? '')
        )
      });
    });
  };

  // Specify how each of the ComboBox values should change when the input
  // field is altered by the user
  let onInputChange = (value) => {
    setFieldState((prevState) => ({
      inputValue: value,
      selectedKey: value === ''
        ? null
        : prevState.selectedKey,
      items: optionList.filter((item) =>
        startsWith(item.name, value)
      )
    }));
  };

  // Show entire list if user opens the menu manually
  let onOpenChange = (isOpen, menuTrigger) => {
    if (menuTrigger === 'manual' && isOpen) {
      setFieldState((prevState) => ({
        inputValue: prevState.inputValue,
        selectedKey: prevState.selectedKey,
        items: optionList
      }));
    }
  };

  // Pass each controlled prop to ComboBox along with their
  // change handlers
  return (
    <MyComboBox
      label="Favorite Animal"
      items={fieldState.items}
      selectedKey={fieldState.selectedKey}
      inputValue={fieldState.inputValue}
      onOpenChange={onOpenChange}
      onSelectionChange={onSelectionChange}
      onInputChange={onInputChange}
    >
      {(item) => <Item>{item.name}</Item>}
    </MyComboBox>
  );
}

<ControlledComboBox />