alpha

ComboBox

ComboBoxes combine a text entry with a picker menu, allowing users to filter longer lists to only the selections matching a query.

install	`yarn add @react-spectrum/combobox`
version	3.0.0-alpha.0
usage	`import {ComboBox, Item, Section} from '@react-spectrum/combobox'`

View guidelines

Example#

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

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

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

Content#

ComboBox follows the Collection Components API, accepting both static and dynamic collections. Similar to Picker, ComboBox accepts <Item> elements as children, each with a key prop. Basic usage of ComboBox, seen in the example above, shows multiple options populated with a string. Static collections, as in this example, 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. Providing the data in this way allows ComboBox to automatically cache the rendering of each item, which dramatically improves performance.

As seen below, an iterable list of options is passed to the ComboBox using the defaultItems prop. Each item accepts a key 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 a key prop is not required. See the Events section for more detail on selection.

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 (
    <>
      <p>Topic id: {majorId}</p>
      <ComboBox
        label="Pick a engineering major"
        defaultItems={options}
        onSelectionChange={setMajorId}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>
    </>
  );
}

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 (
    <>
      <p>Topic id: {majorId}</p>
      <ComboBox
        label="Pick a engineering major"
        defaultItems={options}
        onSelectionChange={setMajorId}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>
    </>
  );
}

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 (
    <>
      <p>
        Topic id:{' '}
        {majorId}
      </p>
      <ComboBox
        label="Pick a engineering major"
        defaultItems={
          options
        }
        onSelectionChange={
          setMajorId
        }>
        {(item) => (
          <Item>
            {item.name}
          </Item>
        )}
      </ComboBox>
    </>
  );
}

Alternatively, passing your list of options to ComboBox's items prop will cause the list of items to be controlled, useful for when you want to provide your own filtering logic. See the Custom Filtering section for more detail.

Trays#

On mobile, ComboBox automatically displays in a tray instead of a popover to improve usability. The tray contains a search field that mobile users can use to filter the options available via text.

Internationalization#

To internationalize a ComboBox, a localized string should be passed to the children of each Item. For languages that are read right-to-left (e.g. Hebrew and Arabic), the layout of the ComboBox is automatically flipped.

Value#

A ComboBox's value is empty by default, but an initial, uncontrolled, value can be provided using the defaultInputValue prop. Alternatively, a controlled value can be provided using the inputValue prop. Note that the input value of the ComboBox does not affect the ComboBox's selected option. See Events for more details on input change events.

function Example() {
  let options = [
    {id: 1, name: 'Adobe Photoshop'},
    {id: 2, name: 'Adobe XD'},
    {id: 3, name: 'Adobe InDesign'},
    {id: 4, name: 'Adobe AfterEffects'},
    {id: 5, name: 'Adobe Illustrator'},
    {id: 6, name: 'Adobe Lightroom'},
    {id: 7, name: 'Adobe Premiere Pro'},
    {id: 8, name: 'Adobe Fresco'},
    {id: 9, name: 'Adobe Dreamweaver'}
  ];
  let [value, setValue] = React.useState('Adobe XD');

  return (
    <Flex gap="size-150" wrap>
      <ComboBox
        label="Adobe product (Uncontrolled)"
        defaultItems={options}
        defaultInputValue={'Adobe XD'}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>

      <ComboBox
        label="Pick an Adobe product (Controlled)"
        defaultItems={options}
        inputValue={value}
        onInputChange={setValue}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>
    </Flex>
  );
}

function Example() {
  let options = [
    {id: 1, name: 'Adobe Photoshop'},
    {id: 2, name: 'Adobe XD'},
    {id: 3, name: 'Adobe InDesign'},
    {id: 4, name: 'Adobe AfterEffects'},
    {id: 5, name: 'Adobe Illustrator'},
    {id: 6, name: 'Adobe Lightroom'},
    {id: 7, name: 'Adobe Premiere Pro'},
    {id: 8, name: 'Adobe Fresco'},
    {id: 9, name: 'Adobe Dreamweaver'}
  ];
  let [value, setValue] = React.useState('Adobe XD');

  return (
    <Flex gap="size-150" wrap>
      <ComboBox
        label="Adobe product (Uncontrolled)"
        defaultItems={options}
        defaultInputValue={'Adobe XD'}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>

      <ComboBox
        label="Pick an Adobe product (Controlled)"
        defaultItems={options}
        inputValue={value}
        onInputChange={setValue}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>
    </Flex>
  );
}

function Example() {
  let options = [
    {
      id: 1,
      name:
        'Adobe Photoshop'
    },
    {
      id: 2,
      name: 'Adobe XD'
    },
    {
      id: 3,
      name:
        'Adobe InDesign'
    },
    {
      id: 4,
      name:
        'Adobe AfterEffects'
    },
    {
      id: 5,
      name:
        'Adobe Illustrator'
    },
    {
      id: 6,
      name:
        'Adobe Lightroom'
    },
    {
      id: 7,
      name:
        'Adobe Premiere Pro'
    },
    {
      id: 8,
      name:
        'Adobe Fresco'
    },
    {
      id: 9,
      name:
        'Adobe Dreamweaver'
    }
  ];
  let [
    value,
    setValue
  ] = React.useState(
    'Adobe XD'
  );

  return (
    <Flex
      gap="size-150"
      wrap>
      <ComboBox
        label="Adobe product (Uncontrolled)"
        defaultItems={
          options
        }
        defaultInputValue={
          'Adobe XD'
        }>
        {(item) => (
          <Item>
            {item.name}
          </Item>
        )}
      </ComboBox>

      <ComboBox
        label="Pick an Adobe product (Controlled)"
        defaultItems={
          options
        }
        inputValue={
          value
        }
        onInputChange={
          setValue
        }>
        {(item) => (
          <Item>
            {item.name}
          </Item>
        )}
      </ComboBox>
    </Flex>
  );
}

Placeholder text that describes the expected value or formatting for the ComboBox can be provided using the placeholder prop. Placeholder text will only appear when the ComboBox is empty, and should not be used as a substitute for labeling the component with a visible label.

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'}
  ];

  return (
    <ComboBox
      width="size-3000"
      label="Pick a engineering major"
      defaultItems={options}
      placeholder="Search engineering majors">
      {(item) => <Item>{item.name}</Item>}
    </ComboBox>
  );
}

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'}
  ];

  return (
    <ComboBox
      width="size-3000"
      label="Pick a engineering major"
      defaultItems={options}
      placeholder="Search engineering majors">
      {(item) => <Item>{item.name}</Item>}
    </ComboBox>
  );
}

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'
    }
  ];

  return (
    <ComboBox
      width="size-3000"
      label="Pick a engineering major"
      defaultItems={
        options
      }
      placeholder="Search engineering majors">
      {(item) => (
        <Item>
          {item.name}
        </Item>
      )}
    </ComboBox>
  );
}

Custom Value#

By default on blur, a ComboBox will either reset its input value to match the selected option's text or clear its input value if an option has not been selected yet. If you would like to allow the end user to provide a custom input value to the ComboBox, the allowsCustomValue prop can be used to override the above behavior.

function Example() {
  let options = [
    {name: 'Apple'},
    {name: 'Banana'},
    {name: 'Orange'},
    {name: 'Honeydew'},
    {name: 'Grapes'},
    {name: 'Watermelon'},
    {name: 'Cantaloupe'},
    {name: 'Pear'}
  ];

  return (
    <>
      <p>
        Please indicate what fruit you would like included with your delivery.
        If your desired choice does not appear in the list feel free to write
        your own selection.
      </p>
      <ComboBox
        label="Preferred fruit"
        defaultItems={options}
        allowsCustomValue>
        {(item) => <Item key={item.name}>{item.name}</Item>}
      </ComboBox>
    </>
  );
}

function Example() {
  let options = [
    {name: 'Apple'},
    {name: 'Banana'},
    {name: 'Orange'},
    {name: 'Honeydew'},
    {name: 'Grapes'},
    {name: 'Watermelon'},
    {name: 'Cantaloupe'},
    {name: 'Pear'}
  ];

  return (
    <>
      <p>
        Please indicate what fruit you would like included
        with your delivery. If your desired choice does not
        appear in the list feel free to write your own
        selection.
      </p>
      <ComboBox
        label="Preferred fruit"
        defaultItems={options}
        allowsCustomValue>
        {(item) => <Item key={item.name}>{item.name}</Item>}
      </ComboBox>
    </>
  );
}

function Example() {
  let options = [
    {name: 'Apple'},
    {name: 'Banana'},
    {name: 'Orange'},
    {name: 'Honeydew'},
    {name: 'Grapes'},
    {name: 'Watermelon'},
    {name: 'Cantaloupe'},
    {name: 'Pear'}
  ];

  return (
    <>
      <p>
        Please indicate
        what fruit you
        would like
        included with
        your delivery. If
        your desired
        choice does not
        appear in the
        list feel free to
        write your own
        selection.
      </p>
      <ComboBox
        label="Preferred fruit"
        defaultItems={
          options
        }
        allowsCustomValue>
        {(item) => (
          <Item
            key={
              item.name
            }>
            {item.name}
          </Item>
        )}
      </ComboBox>
    </>
  );
}

Labeling#

ComboBox can be labeled using the label prop. If the ComboBox is a required field, the isRequired and necessityIndicator props can be used to show a required state.

<ComboBox label="Favorite Animal" isRequired necessityIndicator="icon">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  isRequired
  necessityIndicator="icon">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  isRequired
  necessityIndicator="icon">
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</ComboBox>

<ComboBox label="Favorite Animal" isRequired necessityIndicator="label">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  isRequired
  necessityIndicator="label">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  isRequired
  necessityIndicator="label">
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</ComboBox>

<ComboBox label="Favorite Animal" necessityIndicator="label">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  necessityIndicator="label">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  necessityIndicator="label">
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</ComboBox>

Accessibility#

If a visible label isn't specified, an aria-label must be provided to the ComboBox for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

Internationalization#

In order to internationalize a ComboBox, a localized string should be passed to the label or aria-label prop. When the necessityIndicator prop is set to "label", a localized string will be provided for "(required)" or "(optional)" automatically.

Selection#

Setting a selected option can be done by using the defaultSelectedKey or selectedKey prop. The selected key corresponds to the key of an item. See Events for more details on selection events.

function Example() {
  let options = [
    {id: 1, name: 'Adobe Photoshop'},
    {id: 2, name: 'Adobe XD'},
    {id: 3, name: 'Adobe InDesign'},
    {id: 4, name: 'Adobe AfterEffects'},
    {id: 5, name: 'Adobe Illustrator'},
    {id: 6, name: 'Adobe Lightroom'},
    {id: 7, name: 'Adobe Premiere Pro'},
    {id: 8, name: 'Adobe Fresco'},
    {id: 9, name: 'Adobe Dreamweaver'}
  ];
  let [productId, setProductId] = React.useState(9);

  return (
    <Flex gap="size-150" wrap>
      <ComboBox
        label="Pick an Adobe product (uncontrolled)"
        defaultItems={options}
        defaultSelectedKey={9}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>

      <ComboBox
        label="Pick an Adobe product (controlled)"
        defaultItems={options}
        selectedKey={productId}
        onSelectionChange={(selected) => setProductId(selected)}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>
    </Flex>
  );
}

function Example() {
  let options = [
    {id: 1, name: 'Adobe Photoshop'},
    {id: 2, name: 'Adobe XD'},
    {id: 3, name: 'Adobe InDesign'},
    {id: 4, name: 'Adobe AfterEffects'},
    {id: 5, name: 'Adobe Illustrator'},
    {id: 6, name: 'Adobe Lightroom'},
    {id: 7, name: 'Adobe Premiere Pro'},
    {id: 8, name: 'Adobe Fresco'},
    {id: 9, name: 'Adobe Dreamweaver'}
  ];
  let [productId, setProductId] = React.useState(9);

  return (
    <Flex gap="size-150" wrap>
      <ComboBox
        label="Pick an Adobe product (uncontrolled)"
        defaultItems={options}
        defaultSelectedKey={9}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>

      <ComboBox
        label="Pick an Adobe product (controlled)"
        defaultItems={options}
        selectedKey={productId}
        onSelectionChange={(selected) =>
          setProductId(selected)
        }>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>
    </Flex>
  );
}

function Example() {
  let options = [
    {
      id: 1,
      name:
        'Adobe Photoshop'
    },
    {
      id: 2,
      name: 'Adobe XD'
    },
    {
      id: 3,
      name:
        'Adobe InDesign'
    },
    {
      id: 4,
      name:
        'Adobe AfterEffects'
    },
    {
      id: 5,
      name:
        'Adobe Illustrator'
    },
    {
      id: 6,
      name:
        'Adobe Lightroom'
    },
    {
      id: 7,
      name:
        'Adobe Premiere Pro'
    },
    {
      id: 8,
      name:
        'Adobe Fresco'
    },
    {
      id: 9,
      name:
        'Adobe Dreamweaver'
    }
  ];
  let [
    productId,
    setProductId
  ] = React.useState(9);

  return (
    <Flex
      gap="size-150"
      wrap>
      <ComboBox
        label="Pick an Adobe product (uncontrolled)"
        defaultItems={
          options
        }
        defaultSelectedKey={
          9
        }>
        {(item) => (
          <Item>
            {item.name}
          </Item>
        )}
      </ComboBox>

      <ComboBox
        label="Pick an Adobe product (controlled)"
        defaultItems={
          options
        }
        selectedKey={
          productId
        }
        onSelectionChange={(
          selected
        ) =>
          setProductId(
            selected
          )
        }>
        {(item) => (
          <Item>
            {item.name}
          </Item>
        )}
      </ComboBox>
    </Flex>
  );
}

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 and key prop.

Static items#

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

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

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

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 (
    <ComboBox label="Preferred fruit or vegetable" defaultItems={options}>
      {(item) => (
        <Section key={item.name} items={item.children} title={item.name}>
          {(item) => <Item key={item.name}>{item.name}</Item>}
        </Section>
      )}
    </ComboBox>
  );
}

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 (
    <ComboBox
      label="Preferred fruit or vegetable"
      defaultItems={options}>
      {(item) => (
        <Section
          key={item.name}
          items={item.children}
          title={item.name}>
          {(item) => (
            <Item key={item.name}>{item.name}</Item>
          )}
        </Section>
      )}
    </ComboBox>
  );
}

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 (
    <ComboBox
      label="Preferred fruit or vegetable"
      defaultItems={
        options
      }>
      {(item) => (
        <Section
          key={item.name}
          items={
            item.children
          }
          title={
            item.name
          }>
          {(item) => (
            <Item
              key={
                item.name
              }>
              {item.name}
            </Item>
          )}
        </Section>
      )}
    </ComboBox>
  );
}

Events#

ComboBox supports selection via mouse, keyboard, and touch. You can handle all of these via the onSelectionChange prop. ComboBox will pass the selected key to the onSelectionChange handler. Additionally, ComboBox accepts an onInputChange prop which is triggered whenever the value is edited by the user, whether through typing or option selection.

The example below uses onSelectionChange and onInputChange to update the selection and input value stored in React state.

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 [value, setValue] = React.useState('');
  let [majorId, setMajorId] = React.useState('');

  let onSelectionChange = (id) => {
    setMajorId(id);
  };

  let onInputChange = (value) => {
    setValue(value);
  };

  return (
    <>
      <p>Current selected major id: {majorId}</p>
      <p>Current input text: {value}</p>
      <ComboBox
        label="Pick a engineering major"
        defaultItems={options}
        selectedKey={majorId}
        onSelectionChange={onSelectionChange}
        onInputChange={onInputChange}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>
    </>
  );
}

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 [value, setValue] = React.useState('');
  let [majorId, setMajorId] = React.useState('');

  let onSelectionChange = (id) => {
    setMajorId(id);
  };

  let onInputChange = (value) => {
    setValue(value);
  };

  return (
    <>
      <p>Current selected major id: {majorId}</p>
      <p>Current input text: {value}</p>
      <ComboBox
        label="Pick a engineering major"
        defaultItems={options}
        selectedKey={majorId}
        onSelectionChange={onSelectionChange}
        onInputChange={onInputChange}>
        {(item) => <Item>{item.name}</Item>}
      </ComboBox>
    </>
  );
}

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 [
    value,
    setValue
  ] = React.useState('');
  let [
    majorId,
    setMajorId
  ] = React.useState('');

  let onSelectionChange = (
    id
  ) => {
    setMajorId(id);
  };

  let onInputChange = (
    value
  ) => {
    setValue(value);
  };

  return (
    <>
      <p>
        Current selected
        major id:{' '}
        {majorId}
      </p>
      <p>
        Current input
        text: {value}
      </p>
      <ComboBox
        label="Pick a engineering major"
        defaultItems={
          options
        }
        selectedKey={
          majorId
        }
        onSelectionChange={
          onSelectionChange
        }
        onInputChange={
          onInputChange
        }>
        {(item) => (
          <Item>
            {item.name}
          </Item>
        )}
      </ComboBox>
    </>
  );
}

Fully controlled ComboBox#

When a ComboBox has multiple controlled properties (e.g. isOpen, inputValue, selectedKey), it is important to note that an update to one of these properties will not automatically update the others. Each interaction done in the ComboBox will only trigger its associated event handler. For example, typing in the field will only trigger onInputChange whereas selecting an item from the ComboBox menu will only trigger onSelectionChange so it is your responsibility to update the other controlled properties accordingly.

The below example demonstrates how you would construct the same example above in a completely controlled fashion.

import {useTreeData} from '@react-stately/data';

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 [fieldState, setFieldState] = React.useState({
    isOpen: false,
    selectedKey: '',
    inputValue: ''
  });

  let list = useTreeData({
    initialItems: options
  });

  let onSelectionChange = (key) => {
    setFieldState({
      isOpen: false,
      inputValue: list.getItem(key)?.value.name ?? '',
      selectedKey: key
    });
  };

  let onInputChange = (value) => {
    setFieldState((prevState) => ({
      isOpen: true,
      inputValue: value,
      selectedKey: value === '' ? null : prevState.selectedKey
    }));
  };

  let onOpenChange = (isOpen) => {
    setFieldState((prevState) => ({
      isOpen,
      inputValue: prevState.inputValue,
      selectedKey: prevState.selectedKey
    }));
  };

  return (
    <>
      <p>Current selected major id: {fieldState.selectedKey}</p>
      <p>Current input text: {fieldState.inputValue}</p>
      <ComboBox
        label="Pick a engineering major"
        defaultItems={list.items}
        selectedKey={fieldState.selectedKey}
        inputValue={fieldState.inputValue}
        isOpen={fieldState.isOpen}
        onOpenChange={onOpenChange}
        onSelectionChange={onSelectionChange}
        onInputChange={onInputChange}>
        {(item) => <Item>{item.value.name}</Item>}
      </ComboBox>
    </>
  );
}

import {useTreeData} from '@react-stately/data';

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 [fieldState, setFieldState] = React.useState({
    isOpen: false,
    selectedKey: '',
    inputValue: ''
  });

  let list = useTreeData({
    initialItems: options
  });

  let onSelectionChange = (key) => {
    setFieldState({
      isOpen: false,
      inputValue: list.getItem(key)?.value.name ?? '',
      selectedKey: key
    });
  };

  let onInputChange = (value) => {
    setFieldState((prevState) => ({
      isOpen: true,
      inputValue: value,
      selectedKey:
        value === '' ? null : prevState.selectedKey
    }));
  };

  let onOpenChange = (isOpen) => {
    setFieldState((prevState) => ({
      isOpen,
      inputValue: prevState.inputValue,
      selectedKey: prevState.selectedKey
    }));
  };

  return (
    <>
      <p>
        Current selected major id: {fieldState.selectedKey}
      </p>
      <p>Current input text: {fieldState.inputValue}</p>
      <ComboBox
        label="Pick a engineering major"
        defaultItems={list.items}
        selectedKey={fieldState.selectedKey}
        inputValue={fieldState.inputValue}
        isOpen={fieldState.isOpen}
        onOpenChange={onOpenChange}
        onSelectionChange={onSelectionChange}
        onInputChange={onInputChange}>
        {(item) => <Item>{item.value.name}</Item>}
      </ComboBox>
    </>
  );
}

import {useTreeData} from '@react-stately/data';

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 [
    fieldState,
    setFieldState
  ] = React.useState({
    isOpen: false,
    selectedKey: '',
    inputValue: ''
  });

  let list = useTreeData(
    {
      initialItems: options
    }
  );

  let onSelectionChange = (
    key
  ) => {
    setFieldState({
      isOpen: false,
      inputValue:
        list.getItem(key)
          ?.value.name ??
        '',
      selectedKey: key
    });
  };

  let onInputChange = (
    value
  ) => {
    setFieldState(
      (prevState) => ({
        isOpen: true,
        inputValue: value,
        selectedKey:
          value === ''
            ? null
            : prevState.selectedKey
      })
    );
  };

  let onOpenChange = (
    isOpen
  ) => {
    setFieldState(
      (prevState) => ({
        isOpen,
        inputValue:
          prevState.inputValue,
        selectedKey:
          prevState.selectedKey
      })
    );
  };

  return (
    <>
      <p>
        Current selected
        major id:{' '}
        {
          fieldState.selectedKey
        }
      </p>
      <p>
        Current input
        text:{' '}
        {
          fieldState.inputValue
        }
      </p>
      <ComboBox
        label="Pick a engineering major"
        defaultItems={
          list.items
        }
        selectedKey={
          fieldState.selectedKey
        }
        inputValue={
          fieldState.inputValue
        }
        isOpen={
          fieldState.isOpen
        }
        onOpenChange={
          onOpenChange
        }
        onSelectionChange={
          onSelectionChange
        }
        onInputChange={
          onInputChange
        }>
        {(item) => (
          <Item>
            {
              item.value
                .name
            }
          </Item>
        )}
      </ComboBox>
    </>
  );
}

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.

<ComboBox label="Select action">
  <Item textValue="Add to queue">
    <Add />
    <Text>Add to queue</Text>
    <Text slot="description">Add to current watch queue.</Text>
  </Item>
  <Item textValue="Add review">
    <Draw />
    <Text>Add review</Text>
    <Text slot="description">Post a review for the episode.</Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Bell />
    <Text>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">
    <Alert />
    <Text>Report</Text>
    <Text slot="description">Report an issue/violation.</Text>
  </Item>
</ComboBox>

<ComboBox label="Select action">
  <Item textValue="Add to queue">
    <Add />
    <Text>Add to queue</Text>
    <Text slot="description">
      Add to current watch queue.
    </Text>
  </Item>
  <Item textValue="Add review">
    <Draw />
    <Text>Add review</Text>
    <Text slot="description">
      Post a review for the episode.
    </Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Bell />
    <Text>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">
    <Alert />
    <Text>Report</Text>
    <Text slot="description">
      Report an issue/violation.
    </Text>
  </Item>
</ComboBox>

<ComboBox label="Select action">
  <Item textValue="Add to queue">
    <Add />
    <Text>
      Add to queue
    </Text>
    <Text slot="description">
      Add to current
      watch queue.
    </Text>
  </Item>
  <Item textValue="Add review">
    <Draw />
    <Text>
      Add review
    </Text>
    <Text slot="description">
      Post a review for
      the episode.
    </Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Bell />
    <Text>
      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">
    <Alert />
    <Text>Report</Text>
    <Text slot="description">
      Report an
      issue/violation.
    </Text>
  </Item>
</ComboBox>

Validation#

ComboBox can display a validation state to communicate to the user whether the current value is valid or invalid. Implement your own validation logic in your app and pass either "valid" or "invalid" to the ComboBox via the validationState prop.

The example below illustrates how one would validate if the user has entered a valid email into the ComboBox.

function Example() {
  let [value, setValue] = React.useState('me@email.com');
  let isValid = React.useMemo(
    () => /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/.test(value),
    [value]
  );

  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'}
  ];

  return (
    <ComboBox
      width="size-3000"
      label="To:"
      validationState={isValid ? 'valid' : 'invalid'}
      defaultItems={options}
      value={value}
      onInputChange={setValue}
      placeholder="Enter recipient email"
      allowsCustomValue>
      {(item) => <Item>{item.email}</Item>}
    </ComboBox>
  );
}

function Example() {
  let [value, setValue] = React.useState('me@email.com');
  let isValid = React.useMemo(
    () =>
      /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/.test(
        value
      ),
    [value]
  );

  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'}
  ];

  return (
    <ComboBox
      width="size-3000"
      label="To:"
      validationState={isValid ? 'valid' : 'invalid'}
      defaultItems={options}
      value={value}
      onInputChange={setValue}
      placeholder="Enter recipient email"
      allowsCustomValue>
      {(item) => <Item>{item.email}</Item>}
    </ComboBox>
  );
}

function Example() {
  let [
    value,
    setValue
  ] = React.useState(
    'me@email.com'
  );
  let isValid = React.useMemo(
    () =>
      /^\w+([\.-]?\w+)*@\w+([\.-]?\w+)*(\.\w{2,3})+$/.test(
        value
      ),
    [value]
  );

  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'
    }
  ];

  return (
    <ComboBox
      width="size-3000"
      label="To:"
      validationState={
        isValid
          ? 'valid'
          : 'invalid'
      }
      defaultItems={
        options
      }
      value={value}
      onInputChange={
        setValue
      }
      placeholder="Enter recipient email"
      allowsCustomValue>
      {(item) => (
        <Item>
          {item.email}
        </Item>
      )}
    </ComboBox>
  );
}

Custom Filtering#

By default, ComboBox uses a string "contains" filtering strategy when deciding what items to display in the dropdown menu. This filtering strategy can be overwritten by filtering the list of items yourself and passing the filtered list to the ComboBox via the items prop.

The example below uses a string "startsWith" filter function obtained from the useFilter hook to display items that start with the ComboBox's current input value only.

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 (
    <ComboBox
      width="size-3000"
      label="To:"
      items={filteredItems}
      value={filterValue}
      onInputChange={setFilterValue}
      placeholder="Enter recipient email"
      allowsCustomValue>
      {(item) => <Item>{item.email}</Item>}
    </ComboBox>
  );
}

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 (
    <ComboBox
      width="size-3000"
      label="To:"
      items={filteredItems}
      value={filterValue}
      onInputChange={setFilterValue}
      placeholder="Enter recipient email"
      allowsCustomValue>
      {(item) => <Item>{item.email}</Item>}
    </ComboBox>
  );
}

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 (
    <ComboBox
      width="size-3000"
      label="To:"
      items={
        filteredItems
      }
      value={filterValue}
      onInputChange={
        setFilterValue
      }
      placeholder="Enter recipient email"
      allowsCustomValue>
      {(item) => (
        <Item>
          {item.email}
        </Item>
      )}
    </ComboBox>
  );
}

Trigger options#

By default, the ComboBox's menu is opened when the user types into the input field ("input"). There are two other supported modes: one where the menu opens when the ComboBox is focused ("focus") and the other where the menu only opens when the user clicks or taps on the ComboBox's field button ("manual"). These can be set by providing "focus" or "manual" to the menuTrigger prop. Guidelines on when to use a specific mode can be found here.

<ComboBox label="Select action" menuTrigger="focus">
  <Item textValue="Add to queue">
    <Add />
    <Text>Add to queue</Text>
    <Text slot="description">Add to current watch queue.</Text>
  </Item>
  <Item textValue="Add review">
    <Draw />
    <Text>Add review</Text>
    <Text slot="description">Post a review for the episode.</Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Bell />
    <Text>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">
    <Alert />
    <Text>Report</Text>
    <Text slot="description">Report an issue/violation.</Text>
  </Item>
</ComboBox>

<ComboBox label="Select action" menuTrigger="focus">
  <Item textValue="Add to queue">
    <Add />
    <Text>Add to queue</Text>
    <Text slot="description">
      Add to current watch queue.
    </Text>
  </Item>
  <Item textValue="Add review">
    <Draw />
    <Text>Add review</Text>
    <Text slot="description">
      Post a review for the episode.
    </Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Bell />
    <Text>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">
    <Alert />
    <Text>Report</Text>
    <Text slot="description">
      Report an issue/violation.
    </Text>
  </Item>
</ComboBox>

<ComboBox
  label="Select action"
  menuTrigger="focus">
  <Item textValue="Add to queue">
    <Add />
    <Text>
      Add to queue
    </Text>
    <Text slot="description">
      Add to current
      watch queue.
    </Text>
  </Item>
  <Item textValue="Add review">
    <Draw />
    <Text>
      Add review
    </Text>
    <Text slot="description">
      Post a review for
      the episode.
    </Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Bell />
    <Text>
      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">
    <Alert />
    <Text>Report</Text>
    <Text slot="description">
      Report an
      issue/violation.
    </Text>
  </Item>
</ComboBox>

<ComboBox label="Select action" menuTrigger="manual">
  <Item textValue="Add to queue">
    <Add />
    <Text>Add to queue</Text>
    <Text slot="description">Add to current watch queue.</Text>
  </Item>
  <Item textValue="Add review">
    <Draw />
    <Text>Add review</Text>
    <Text slot="description">Post a review for the episode.</Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Bell />
    <Text>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">
    <Alert />
    <Text>Report</Text>
    <Text slot="description">Report an issue/violation.</Text>
  </Item>
</ComboBox>

<ComboBox label="Select action" menuTrigger="manual">
  <Item textValue="Add to queue">
    <Add />
    <Text>Add to queue</Text>
    <Text slot="description">
      Add to current watch queue.
    </Text>
  </Item>
  <Item textValue="Add review">
    <Draw />
    <Text>Add review</Text>
    <Text slot="description">
      Post a review for the episode.
    </Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Bell />
    <Text>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">
    <Alert />
    <Text>Report</Text>
    <Text slot="description">
      Report an issue/violation.
    </Text>
  </Item>
</ComboBox>

<ComboBox
  label="Select action"
  menuTrigger="manual">
  <Item textValue="Add to queue">
    <Add />
    <Text>
      Add to queue
    </Text>
    <Text slot="description">
      Add to current
      watch queue.
    </Text>
  </Item>
  <Item textValue="Add review">
    <Draw />
    <Text>
      Add review
    </Text>
    <Text slot="description">
      Post a review for
      the episode.
    </Text>
  </Item>
  <Item textValue="Subscribe to series">
    <Bell />
    <Text>
      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">
    <Alert />
    <Text>Report</Text>
    <Text slot="description">
      Report an
      issue/violation.
    </Text>
  </Item>
</ComboBox>

Props#

Name	Type	Default	Description
`children`	`CollectionChildren<T>`	—	The contents of the collection.
`isQuiet`	`boolean`	—	Whether the ComboBox should be displayed with a quiet style.
`direction`	`'bottom' \| 'top'`	`'bottom'`	Direction the menu will render relative to the ComboBox.
`defaultItems`	`Iterable<T>`	—	The list of ComboBox items (uncontrolled).
`items`	`Iterable<T>`	—	The list of ComboBox items (controlled).
`isOpen`	`boolean`	—	Sets the open state of the menu.
`defaultOpen`	`boolean`	—	Sets the default open state of the menu.
`inputValue`	`string`	—	The value of the ComboBox input (controlled).
`defaultInputValue`	`string`	—	The default value of the ComboBox input (uncontrolled).
`allowsCustomValue`	`boolean`	—	Whether the ComboBox allows a non-item matching input value to be set.
`menuTrigger`	`'focus' \| 'input' \| 'manual'`	`'input'`	The interaction required to display the ComboBox menu.
`shouldFlip`	`boolean`	`true`	Whether the menu should automatically flip direction when space is limited.
`disabledKeys`	`Iterable<Key>`	—	The item keys that are disabled. These items cannot be selected, focused, or otherwise interacted with.
`disallowEmptySelection`	`boolean`	—	Whether the collection allows empty selection.
`selectedKey`	`Key`	—	The currently selected key in the collection (controlled).
`defaultSelectedKey`	`Key`	—	The initial selected key in the collection (uncontrolled).
`isDisabled`	`boolean`	—	Whether the input is disabled.
`isReadOnly`	`boolean`	—	Whether the input can be selected but not changed by the user.
`placeholder`	`string`	—	Temporary text that occupies the text input when it is empty.
`validationState`	`ValidationState`	—	Whether the input should display its "valid" or "invalid" visual styling.
`isRequired`	`boolean`	—	Whether user input is required on the input before form submission. Often paired with the `necessityIndicator` prop to add a visual indicator to the input.
`autoFocus`	`boolean`	—	Whether the element should receive focus on render.
`labelPosition`	`LabelPosition`	`'top'`	The label's overall position relative to the element it is labeling.
`labelAlign`	`Alignment`	`'start'`	The label's horizontal alignment relative to the element it is labeling.
`necessityIndicator`	`NecessityIndicator`	`'icon'`	Whether the required state should be shown as an icon or text.
`label`	`ReactNode`	—	The content to display as the label.

Events

Name	Type	Default	Description
`onOpenChange`	`( (isOpen: boolean )) => void`	—	Method that is called when the open state of the menu changes.
`onInputChange`	`( (value: string )) => void`	—	Handler that is called when the ComboBox input value changes.
`onSelectionChange`	`( (key: Key )) => any`	—	Handler that is called when the selection changes.
`onFocus`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element receives focus.
`onBlur`	`( (e: FocusEvent )) => void`	—	Handler that is called when the element loses focus.
`onFocusChange`	`( (isFocused: boolean )) => void`	—	Handler that is called when the element's focus status changes.
`onKeyDown`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is pressed.
`onKeyUp`	`( (e: KeyboardEvent )) => void`	—	Handler that is called when a key is released.

Layout

Name	Type	Default	Description
`flex`	`string \| number \| boolean`	—	When used in a flex layout, specifies how the element will grow or shrink to fit the space available. See MDN.
`flexGrow`	`number`	—	When used in a flex layout, specifies how the element will grow to fit the space available. See MDN.
`flexShrink`	`number`	—	When used in a flex layout, specifies how the element will shrink to fit the space available. See MDN.
`flexBasis`	`number \| string`	—	When used in a flex layout, specifies the initial main size of the element. See MDN.
`alignSelf`	`'auto' \| 'normal' \| 'start' \| 'end' \| 'center' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'stretch'`	—	Overrides the `alignItems` property of a flex or grid container. See MDN.
`justifySelf`	`'auto' \| 'normal' \| 'start' \| 'end' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'center' \| 'left' \| 'right' \| 'stretch'`	—	Specifies how the element is justified inside a flex or grid container. See MDN.
`order`	`number`	—	The layout order for the element within a flex or grid container. See MDN.
`gridArea`	`string`	—	When used in a grid layout, specifies the named grid area that the element should be placed in within the grid. See MDN.
`gridColumn`	`string`	—	When used in a grid layout, specifies the column the element should be placed in within the grid. See MDN.
`gridRow`	`string`	—	When used in a grid layout, specifies the row the element should be placed in within the grid. See MDN.
`gridColumnStart`	`string`	—	When used in a grid layout, specifies the starting column to span within the grid. See MDN.
`gridColumnEnd`	`string`	—	When used in a grid layout, specifies the ending column to span within the grid. See MDN.
`gridRowStart`	`string`	—	When used in a grid layout, specifies the starting row to span within the grid. See MDN.
`gridRowEnd`	`string`	—	When used in a grid layout, specifies the ending row to span within the grid. See MDN.

Spacing

Name	Type	Default	Description
`margin`	`DimensionValue`	—	The margin for all four sides of the element. See MDN.
`marginTop`	`DimensionValue`	—	The margin for the top side of the element. See MDN.
`marginBottom`	`DimensionValue`	—	The margin for the bottom side of the element. See MDN.
`marginStart`	`DimensionValue`	—	The margin for the logical start side of the element, depending on layout direction. See MDN.
`marginEnd`	`DimensionValue`	—	The margin for the logical end side of an element, depending on layout direction. See MDN.
`marginX`	`DimensionValue`	—	The margin for both the left and right sides of the element. See MDN.
`marginY`	`DimensionValue`	—	The margin for both the top and bottom sides of the element. See MDN.

Sizing

Name	Type	Default	Description
`width`	`DimensionValue`	—	The width of the element. See MDN.
`minWidth`	`DimensionValue`	—	The minimum width of the element. See MDN.
`maxWidth`	`DimensionValue`	—	The maximum width of the element. See MDN.
`height`	`DimensionValue`	—	The height of the element. See MDN.
`minHeight`	`DimensionValue`	—	The minimum height of the element. See MDN.
`maxHeight`	`DimensionValue`	—	The maximum height of the element. See MDN.

Positioning

Name	Type	Default	Description
`position`	`'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'`	—	Specifies how the element is positioned. See MDN.
`top`	`DimensionValue`	—	The top position for the element. See MDN.
`bottom`	`DimensionValue`	—	The bottom position for the element. See MDN.
`left`	`DimensionValue`	—	The left position for the element. See MDN. Consider using `start` instead for RTL support.
`right`	`DimensionValue`	—	The right position for the element. See MDN. Consider using `start` instead for RTL support.
`start`	`DimensionValue`	—	The logical start position for the element, depending on layout direction. See MDN.
`end`	`DimensionValue`	—	The logical end position for the element, depending on layout direction. See MDN.
`zIndex`	`number`	—	The stacking order for the element. See MDN.
`isHidden`	`boolean`	—	Hides the element.

Accessibility

Name	Type	Default	Description
`id`	`string`	—	The element's unique identifier. See MDN.

Advanced

Name	Type	Default	Description
`UNSAFE_className`	`string`	—	Sets the CSS className for the element. Only use as a last resort. Use style props instead.
`UNSAFE_style`	`CSSProperties`	—	Sets inline style for the element. Only use as a last resort. Use style props instead.

Visual options#

Label alignment and position#

View guidelines

By default, the label is positioned above the ComboBox. The labelPosition prop can be used to position the label to the side. The labelAlign prop can be used to align the label as "start" or "end". For left-to-right (LTR) languages, "start" refers to the left most edge of the ComboBox and "end" refers to the right most edge. For right-to-left (RTL) languages, this is flipped.

<ComboBox label="Favorite Animal" labelPosition="side" labelAlign="end">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  labelPosition="side"
  labelAlign="end">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  labelPosition="side"
  labelAlign="end">
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</ComboBox>

Quiet#

View guidelines

<ComboBox label="Favorite Animal" isQuiet>
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox label="Favorite Animal" isQuiet>
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  isQuiet>
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</ComboBox>

Disabled#

View guidelines

<ComboBox label="Favorite Animal" isDisabled>
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox label="Favorite Animal" isDisabled>
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  isDisabled>
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</ComboBox>

Read only#

View guidelines

<ComboBox label="Favorite Animal" isReadOnly selectedKey="red panda">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  isReadOnly
  selectedKey="red panda">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  isReadOnly
  selectedKey="red panda">
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</ComboBox>

Custom widths#

View guidelines

<ComboBox label="Favorite Animal" width="size-6000" maxWidth="100%">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  width="size-6000"
  maxWidth="100%">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  width="size-6000"
  maxWidth="100%">
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</ComboBox>

<ComboBox label="Favorite Animal" direction="top">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox label="Favorite Animal" direction="top">
  <Item key="red panda">Red Panda</Item>
  <Item key="cat">Cat</Item>
  <Item key="dog">Dog</Item>
  <Item key="aardvark">Aardvark</Item>
  <Item key="kangaroo">Kangaroo</Item>
  <Item key="snake">Snake</Item>
</ComboBox>

<ComboBox
  label="Favorite Animal"
  direction="top">
  <Item key="red panda">
    Red Panda
  </Item>
  <Item key="cat">
    Cat
  </Item>
  <Item key="dog">
    Dog
  </Item>
  <Item key="aardvark">
    Aardvark
  </Item>
  <Item key="kangaroo">
    Kangaroo
  </Item>
  <Item key="snake">
    Snake
  </Item>
</ComboBox>

The open state of the menu can be controlled via the defaultOpen and isOpen props.

function Example() {
  let [open, setOpen] = React.useState(false);
  let [favorite, setFavorite] = React.useState('red panda');

  return (
    <ComboBox
      label="Favorite Animal"
      isOpen={open}
      onOpenChange={setOpen}
      selectedKey={favorite}
      onSelectionChange={(selected) => setFavorite(selected)}>
      <Item key="red panda">Red Panda</Item>
      <Item key="cat">Cat</Item>
      <Item key="dog">Dog</Item>
      <Item key="aardvark">Aardvark</Item>
      <Item key="kangaroo">Kangaroo</Item>
      <Item key="snake">Snake</Item>
    </ComboBox>
  );
}

function Example() {
  let [open, setOpen] = React.useState(false);
  let [favorite, setFavorite] = React.useState('red panda');

  return (
    <ComboBox
      label="Favorite Animal"
      isOpen={open}
      onOpenChange={setOpen}
      selectedKey={favorite}
      onSelectionChange={(selected) =>
        setFavorite(selected)
      }>
      <Item key="red panda">Red Panda</Item>
      <Item key="cat">Cat</Item>
      <Item key="dog">Dog</Item>
      <Item key="aardvark">Aardvark</Item>
      <Item key="kangaroo">Kangaroo</Item>
      <Item key="snake">Snake</Item>
    </ComboBox>
  );
}

function Example() {
  let [
    open,
    setOpen
  ] = React.useState(
    false
  );
  let [
    favorite,
    setFavorite
  ] = React.useState(
    'red panda'
  );

  return (
    <ComboBox
      label="Favorite Animal"
      isOpen={open}
      onOpenChange={
        setOpen
      }
      selectedKey={
        favorite
      }
      onSelectionChange={(
        selected
      ) =>
        setFavorite(
          selected
        )
      }>
      <Item key="red panda">
        Red Panda
      </Item>
      <Item key="cat">
        Cat
      </Item>
      <Item key="dog">
        Dog
      </Item>
      <Item key="aardvark">
        Aardvark
      </Item>
      <Item key="kangaroo">
        Kangaroo
      </Item>
      <Item key="snake">
        Snake
      </Item>
    </ComboBox>
  );
}

ComboBox

Example#

Content#

Trays#

Internationalization#

Value#

Custom Value#

Labeling#

Accessibility#

Internationalization#

Selection#

Sections#

Static items#

Dynamic items#

Events#

Fully controlled ComboBox#

Complex items#

Validation#

Custom Filtering#

Trigger options#

Props#

Visual options#

Label alignment and position#

Quiet#

Disabled#

Read only#

Custom widths#

Menu direction#

Menu state#