MultiComboBox

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

Static Collection

The MultiComboBox component can either render static or dynamic collections of data. For simple combobox components that need to render a list of pre-defined data a static collection should be used. Static collections cannot be changed over time.

<MultiComboBox label='What is your favorite fruit?'>
  <Item key='apples'>Apples</Item>
  <Item key='bananas'>Bananas</Item>
  <Item key='grapes'>Grapes</Item>
  <Item key='oranges'>Oranges</Item>
</MultiComboBox>

<MultiComboBox label='What is your favorite fruit?'>
  <Item key='apples'>Apples</Item>
  <Item key='bananas'>Bananas</Item>
  <Item key='grapes'>Grapes</Item>
  <Item key='oranges'>Oranges</Item>
</MultiComboBox>

<MultiComboBox label="What is your favorite fruit?">
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Dynamic Collection

For data that is non-static, such as data fetched from a backend, the MultiComboBox component supports dynamic collections. Dynamic collections support adding, updating and removing of the data that is being rendered.

function Example() {
  const allFruits = [
    { id: 1, name: 'Apples' },
    { id: 2, name: 'Bananas' },
    { id: 3, name: 'Grapes' },
    { id: 4, name: 'Oranges' }
  ];

  const [fruits, setFruits] = useState(allFruits);

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      items={fruits}
      onInputChange={(input) =>
        setFruits(allFruits.filter(({ name }) => name.includes(input)))}
    >
      {(item) => <Item key={item.id}>{item.name}</Item>}
    </MultiComboBox>
  );
}

function Example() {
  const allFruits = [
    { id: 1, name: 'Apples' },
    { id: 2, name: 'Bananas' },
    { id: 3, name: 'Grapes' },
    { id: 4, name: 'Oranges' }
  ];

  const [fruits, setFruits] = useState(allFruits);

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      items={fruits}
      onInputChange={(input) =>
        setFruits(
          allFruits.filter(({ name }) =>
            name.includes(input)
          )
        )}
    >
      {(item) => <Item key={item.id}>{item.name}</Item>}
    </MultiComboBox>
  );
}

function Example() {
  const allFruits = [
    {
      id: 1,
      name: 'Apples'
    },
    {
      id: 2,
      name: 'Bananas'
    },
    {
      id: 3,
      name: 'Grapes'
    },
    {
      id: 4,
      name: 'Oranges'
    }
  ];

  const [
    fruits,
    setFruits
  ] = useState(
    allFruits
  );

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      items={fruits}
      onInputChange={(
        input
      ) =>
        setFruits(
          allFruits
            .filter((
              { name }
            ) =>
              name
                .includes(
                  input
                )
            )
        )}
    >
      {(item) => (
        <Item
          key={item.id}
        >
          {item.name}
        </Item>
      )}
    </MultiComboBox>
  );
}

Asynchronous Fetching

The MultiComboBox component supports asynchronous fetching of data via the onLoadMoreItems prop. The combobox component uses its built-in infinite scrolling to achieve this. This means that when the user reaches the bottom of the list, the component will automatically load more data. If you provide an isLoading prop, the MultiComboBox component will show a Spinner component, to indicate to the user, that more data is being fetched.

function Example() {
  const defaultSelectedKeys = ['R5-D4', 'Leia Organa', 'Quarsh Panaka'];

  const list = useAsyncListState({
    async loadItems(state) {
      let { cursor, signal, filterValue, items } = state;

      if (cursor) {
        cursor = cursor.replace(/^http:\/\//i, 'https://');
      }

      const response = await fetch(
        cursor || `https://swapi.py4e.com/api/people/?search=${filterValue}`,
        { signal }
      );
      const { results, next } = await response.json();

      return { ...state, items: results, cursor: next };
    },
    initialItems: defaultSelectedKeys.map((name) => ({ name }))
  });

  return (
    <MultiComboBox
      label="Favorite Star Wars character?"
      items={list.items}
      onInputChange={list.setFilterValue}
      loadingState={list.loadingState}
      onLoadMoreItems={list.loadMoreItems}
      defaultSelectedKeys={defaultSelectedKeys}
    >
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </MultiComboBox>
  );
}

function Example() {
  const defaultSelectedKeys = [
    'R5-D4',
    'Leia Organa',
    'Quarsh Panaka'
  ];

  const list = useAsyncListState({
    async loadItems(state) {
      let { cursor, signal, filterValue, items } = state;

      if (cursor) {
        cursor = cursor.replace(/^http:\/\//i, 'https://');
      }

      const response = await fetch(
        cursor ||
          `https://swapi.py4e.com/api/people/?search=${filterValue}`,
        { signal }
      );
      const { results, next } = await response.json();

      return { ...state, items: results, cursor: next };
    },
    initialItems: defaultSelectedKeys.map((name) => ({
      name
    }))
  });

  return (
    <MultiComboBox
      label="Favorite Star Wars character?"
      items={list.items}
      onInputChange={list.setFilterValue}
      loadingState={list.loadingState}
      onLoadMoreItems={list.loadMoreItems}
      defaultSelectedKeys={defaultSelectedKeys}
    >
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </MultiComboBox>
  );
}

function Example() {
  const defaultSelectedKeys =
    [
      'R5-D4',
      'Leia Organa',
      'Quarsh Panaka'
    ];

  const list =
    useAsyncListState({
      async loadItems(
        state
      ) {
        let {
          cursor,
          signal,
          filterValue,
          items
        } = state;

        if (cursor) {
          cursor = cursor
            .replace(
              /^http:\/\//i,
              'https://'
            );
        }

        const response =
          await fetch(
            cursor ||
              `https://swapi.py4e.com/api/people/?search=${filterValue}`,
            { signal }
          );
        const {
          results,
          next
        } =
          await response
            .json();

        return {
          ...state,
          items: results,
          cursor: next
        };
      },
      initialItems:
        defaultSelectedKeys
          .map((
            name
          ) => ({
            name
          }))
    });

  return (
    <MultiComboBox
      label="Favorite Star Wars character?"
      items={list.items}
      onInputChange={list
        .setFilterValue}
      loadingState={list
        .loadingState}
      onLoadMoreItems={list
        .loadMoreItems}
      defaultSelectedKeys={defaultSelectedKeys}
    >
      {(item) => (
        <Item
          key={item.name}
        >
          {item.name}
        </Item>
      )}
    </MultiComboBox>
  );
}

Uncontrolled Value

By default, the MultiComboBox component handles its selection uncontrolled. In the uncontrolled variant you can pass in a defaultSelectedKeys to combobox a value by default. The key that is being referenced here is the value that is passed to the Item component as a key prop, so in this case item.name.

function Example() {
  const fruits = [
    { id: 1, name: 'Apples' },
    { id: 2, name: 'Bananas' },
    { id: 3, name: 'Grapes' },
    { id: 4, name: 'Oranges' }
  ];

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      items={fruits}
      defaultSelectedKeys={['Grapes']}
      defaultInputValue="App"
    >
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </MultiComboBox>
  );
}

function Example() {
  const fruits = [
    { id: 1, name: 'Apples' },
    { id: 2, name: 'Bananas' },
    { id: 3, name: 'Grapes' },
    { id: 4, name: 'Oranges' }
  ];

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      items={fruits}
      defaultSelectedKeys={['Grapes']}
      defaultInputValue="App"
    >
      {(item) => <Item key={item.name}>{item.name}</Item>}
    </MultiComboBox>
  );
}

function Example() {
  const fruits = [
    {
      id: 1,
      name: 'Apples'
    },
    {
      id: 2,
      name: 'Bananas'
    },
    {
      id: 3,
      name: 'Grapes'
    },
    {
      id: 4,
      name: 'Oranges'
    }
  ];

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      items={fruits}
      defaultSelectedKeys={[
        'Grapes'
      ]}
      defaultInputValue="App"
    >
      {(item) => (
        <Item
          key={item.name}
        >
          {item.name}
        </Item>
      )}
    </MultiComboBox>
  );
}

Controlled Value

The use the controlled selection variant, you can use the selectedKeys and onSelectionChange props together.

function Example() {
  const fruits = [
    {id: 1, name: 'Apples'},
    {id: 2, name: 'Bananas'},
    {id: 3, name: 'Grapes'},
    {id: 4, name: 'Oranges'}
  ];

  const [{selectedKeys, inputValue}, setFieldState] = useState({
    inputValue: '',
    selectedKeys: new Set(['Bananas'])
  });

  const onInputChangeHandler = (value) => {
    setFieldState((prevState) => ({
      ...prevState,
      inputValue: value
    }));
  };

  const onSelectionChangeHandler = (keys) => {
    setFieldState({
      inputValue: '',
      selectedKeys: keys
    });
  };

  return (
    <div>
      <MultiComboBox
        label='What is your favorite fruit?'
        items={fruits}
        selectedKeys={selectedKeys}
        inputValue={inputValue}
        onSelectionChange={onSelectionChangeHandler}
        onInputChange={onInputChangeHandler}
      >
        {(item) => <Item key={item.name}>{item.name}</Item>}
      </MultiComboBox>
      
      <div>Value: {selectedKeys}</div>
    </div>
  );
}

function Example() {
  const fruits = [
    { id: 1, name: 'Apples' },
    { id: 2, name: 'Bananas' },
    { id: 3, name: 'Grapes' },
    { id: 4, name: 'Oranges' }
  ];

  const [{ selectedKeys, inputValue }, setFieldState] =
    useState({
      inputValue: '',
      selectedKeys: new Set(['Bananas'])
    });

  const onInputChangeHandler = (value) => {
    setFieldState((prevState) => ({
      ...prevState,
      inputValue: value
    }));
  };

  const onSelectionChangeHandler = (keys) => {
    setFieldState({
      inputValue: '',
      selectedKeys: keys
    });
  };

  return (
    <div>
      <MultiComboBox
        label="What is your favorite fruit?"
        items={fruits}
        selectedKeys={selectedKeys}
        inputValue={inputValue}
        onSelectionChange={onSelectionChangeHandler}
        onInputChange={onInputChangeHandler}
      >
        {(item) => <Item key={item.name}>{item.name}</Item>}
      </MultiComboBox>

      <div>Value: {selectedKeys}</div>
    </div>
  );
}

function Example() {
  const fruits = [
    {
      id: 1,
      name: 'Apples'
    },
    {
      id: 2,
      name: 'Bananas'
    },
    {
      id: 3,
      name: 'Grapes'
    },
    {
      id: 4,
      name: 'Oranges'
    }
  ];

  const [
    {
      selectedKeys,
      inputValue
    },
    setFieldState
  ] = useState({
    inputValue: '',
    selectedKeys:
      new Set([
        'Bananas'
      ])
  });

  const onInputChangeHandler =
    (value) => {
      setFieldState((
        prevState
      ) => ({
        ...prevState,
        inputValue: value
      }));
    };

  const onSelectionChangeHandler =
    (keys) => {
      setFieldState({
        inputValue: '',
        selectedKeys:
          keys
      });
    };

  return (
    <div>
      <MultiComboBox
        label="What is your favorite fruit?"
        items={fruits}
        selectedKeys={selectedKeys}
        inputValue={inputValue}
        onSelectionChange={onSelectionChangeHandler}
        onInputChange={onInputChangeHandler}
      >
        {(item) => (
          <Item
            key={item
              .name}
          >
            {item.name}
          </Item>
        )}
      </MultiComboBox>

      <div>
        Value:{' '}
        {selectedKeys}
      </div>
    </div>
  );
}

Static Sections

To group items by sections you can wrap the items in a Section component.

<MultiComboBox label='What is your favorite fruit?'>
  <Section title='Category A'>
    <Item key='apples'>Apples</Item>
    <Item key='bananas'>Bananas</Item>
  </Section>
  <Section title='Category B'>
    <Item key='grapes'>Grapes</Item>
    <Item key='oranges'>Oranges</Item>
  </Section>
</MultiComboBox>

<MultiComboBox label='What is your favorite fruit?'>
  <Section title='Category A'>
    <Item key='apples'>Apples</Item>
    <Item key='bananas'>Bananas</Item>
  </Section>
  <Section title='Category B'>
    <Item key='grapes'>Grapes</Item>
    <Item key='oranges'>Oranges</Item>
  </Section>
</MultiComboBox>

<MultiComboBox label="What is your favorite fruit?">
  <Section title="Category A">
    <Item key="apples">
      Apples
    </Item>
    <Item key="bananas">
      Bananas
    </Item>
  </Section>
  <Section title="Category B">
    <Item key="grapes">
      Grapes
    </Item>
    <Item key="oranges">
      Oranges
    </Item>
  </Section>
</MultiComboBox>

Dynamic Sections

To render a group of sections dynamically you can create them from a hierarchical data structure.

function Example() {
  const fruits = [
    {
      title: 'Category A',
      items: [
        {id: 1, name: 'Apples'},
        {id: 2, name: 'Bananas'}
      ]
    },
    {
      title: 'Category B',
      items: [
        {id: 3, name: 'Grapes'},
        {id: 4, name: 'Oranges'}
      ]
    }
  ];

  return (
    <MultiComboBox label='What is your favorite fruit?' items={fruits}>
      {(section) => (
        <Section title={section.title} items={section.items}>
          {(item) => <Item key={item.name}>{item.name}</Item>}
        </Section>
      )}
    </MultiComboBox>
  );
}

function Example() {
  const fruits = [
    {
      title: 'Category A',
      items: [
        { id: 1, name: 'Apples' },
        { id: 2, name: 'Bananas' }
      ]
    },
    {
      title: 'Category B',
      items: [
        { id: 3, name: 'Grapes' },
        { id: 4, name: 'Oranges' }
      ]
    }
  ];

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      items={fruits}
    >
      {(section) => (
        <Section
          title={section.title}
          items={section.items}
        >
          {(item) => (
            <Item key={item.name}>{item.name}</Item>
          )}
        </Section>
      )}
    </MultiComboBox>
  );
}

function Example() {
  const fruits = [
    {
      title:
        'Category A',
      items: [
        {
          id: 1,
          name: 'Apples'
        },
        {
          id: 2,
          name: 'Bananas'
        }
      ]
    },
    {
      title:
        'Category B',
      items: [
        {
          id: 3,
          name: 'Grapes'
        },
        {
          id: 4,
          name: 'Oranges'
        }
      ]
    }
  ];

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      items={fruits}
    >
      {(section) => (
        <Section
          title={section
            .title}
          items={section
            .items}
        >
          {(item) => (
            <Item
              key={item
                .name}
            >
              {item.name}
            </Item>
          )}
        </Section>
      )}
    </MultiComboBox>
  );
}

Required

To indicate to the user that the MultiComboBox is required you can use the isRequired prop.

<MultiComboBox label='What is your favorite fruit?' isRequired>
  <Item key='apples'>Apples</Item>
  <Item key='bananas'>Bananas</Item>
  <Item key='grapes'>Grapes</Item>
  <Item key='oranges'>Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  isRequired
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  isRequired
>
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Validation

The MultiComboBox component has built-in accessible validation support. To indicate whether the field is valid or not you can use the errorMessage prop.

function Example() {
  const [value, setValue] = useState();

  return (
    <MultiComboBox 
      label='What is your favorite fruit?' 
      isRequired 
      errorMessage={(!value || value.size < 1) && 'This field is required.'}
      selectedKeys={value}
      onSelectionChange={setValue}
    >
      <Item key='apples'>Apples</Item>
      <Item key='bananas'>Bananas</Item>
      <Item key='grapes'>Grapes</Item>
      <Item key='oranges'>Oranges</Item>
    </MultiComboBox>
  );
}

function Example() {
  const [value, setValue] = useState();

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      isRequired
      errorMessage={(!value || value.size < 1) &&
        'This field is required.'}
      selectedKeys={value}
      onSelectionChange={setValue}
    >
      <Item key="apples">Apples</Item>
      <Item key="bananas">Bananas</Item>
      <Item key="grapes">Grapes</Item>
      <Item key="oranges">Oranges</Item>
    </MultiComboBox>
  );
}

function Example() {
  const [
    value,
    setValue
  ] = useState();

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      isRequired
      errorMessage={(!value ||
        value.size <
          1) &&
        'This field is required.'}
      selectedKeys={value}
      onSelectionChange={setValue}
    >
      <Item key="apples">
        Apples
      </Item>
      <Item key="bananas">
        Bananas
      </Item>
      <Item key="grapes">
        Grapes
      </Item>
      <Item key="oranges">
        Oranges
      </Item>
    </MultiComboBox>
  );
}

Description

To give further instructions or more verbose examples to the user about a MultiComboBox you can provide a description prop. Avoid using error like tone of voice of the message. If an errorMessage prop is provided it will replace the description.

<MultiComboBox
  label="What is your favorite fruit?"
  description="An enumeration of the essential qualities of a thing or species"
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  description="An enumeration of the essential qualities of a thing or species"
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  description="An enumeration of the essential qualities of a thing or species"
>
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Contextual Help

To offer the user contextual help, the MultiComboBox supports passing a contextualHelp prop, that accepts a ReactNode.

<MultiComboBox
  label='What is your favorite fruit?' 
  contextualHelp={(
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. 
        </Text>
      </Content>
    </ContextualHelp>
  )} 
>
  <Item key='apples'>Apples</Item>
  <Item key='bananas'>Bananas</Item>
  <Item key='grapes'>Grapes</Item>
  <Item key='oranges'>Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>Lorem Ipsum</Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum dolor sit amet, consectetur
          adipiscing elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  contextualHelp={
    <ContextualHelp variant="info">
      <Header>
        <Heading>
          Lorem Ipsum
        </Heading>
      </Header>
      <Content>
        <Text>
          Lorem ipsum
          dolor sit
          amet,
          consectetur
          adipiscing
          elit.
        </Text>
      </Content>
    </ContextualHelp>
  }
>
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Disabled

The MultiComboBox component can be disabled via the isDisabled prop.

<MultiComboBox
  label="What is your favorite fruit?"
  isDisabled
  defaultSelectedKey="grapes"
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  isDisabled
  defaultSelectedKey="grapes"
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  isDisabled
  defaultSelectedKey="grapes"
>
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Read Only

The MultiComboBox component can be marked as read only via the isReadOnly prop.

<MultiComboBox
  label="What is your favorite fruit?"
  isReadOnly
  defaultSelectedKey="bananas"
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  isReadOnly
  defaultSelectedKey="bananas"
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  isReadOnly
  defaultSelectedKey="bananas"
>
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Menu Direction

By default, the menu of The MultiComboBox component opens to the bottom. If the window does not offer enough space to fully open the menu, it automatically opens it to the top. However, you can control this behaviour yourself via the placement prop.

<MultiComboBox label="What is your favorite fruit?" placement="top end">
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  placement="top end"
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  placement="top end"
>
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Menu Alignment

The menu is by default aligned to the start of the input component. If the content of the menu is longer than the input that shows the value of The MultiComboBox component, the menu will outgrow the end of the input. However, this behaviour can be reversed with the placement prop.

<MultiComboBox label="What is your favorite fruit?" placement="top end">
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  placement="top end"
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  placement="top end"
>
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Labeling

A MultiComboBox component should be labeled with a visual text through the label prop. If the MultiComboBox does not include a textual label, an aria-label or aria-labelledby prop need to be provided to support assistive technology such as screen readers.

<MultiComboBox label='What is your favorite fruit?'>
  <Item key='apples'>Apples</Item>
  <Item key='bananas'>Bananas</Item>
  <Item key='grapes'>Grapes</Item>
  <Item key='oranges'>Oranges</Item>
</MultiComboBox>

<MultiComboBox label='What is your favorite fruit?'>
  <Item key='apples'>Apples</Item>
  <Item key='bananas'>Bananas</Item>
  <Item key='grapes'>Grapes</Item>
  <Item key='oranges'>Oranges</Item>
</MultiComboBox>

<MultiComboBox label="What is your favorite fruit?">
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Label Alignment

For languages that are read left-to-right (LTR), such as English, the label of The MultiComboBox component is displayed on the left side of the input. For right-to-left (RTL) languages, such as Arabic, this is flipped. You can control the position of the label through the labelPlacement prop.

<MultiComboBox label="What is your favorite fruit?" labelPlacement="top end">
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  labelPlacement="top end"
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  labelPlacement="top end"
>
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Label Position

By default, the label of The MultiComboBox component is displayed above its input. With the labelPlacement prop this placement can be adjusted to be on the side of the input.

<MultiComboBox label="What is your favorite fruit?" labelPlacement="side end">
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  labelPlacement="side end"
>
  <Item key="apples">Apples</Item>
  <Item key="bananas">Bananas</Item>
  <Item key="grapes">Grapes</Item>
  <Item key="oranges">Oranges</Item>
</MultiComboBox>

<MultiComboBox
  label="What is your favorite fruit?"
  labelPlacement="side end"
>
  <Item key="apples">
    Apples
  </Item>
  <Item key="bananas">
    Bananas
  </Item>
  <Item key="grapes">
    Grapes
  </Item>
  <Item key="oranges">
    Oranges
  </Item>
</MultiComboBox>

Controlled Menu State

The open state of the menu can be controlled via the isOpen prop.

function Example() {
  const [isOpen, setOpen] = useState(false);

  const handleOpenChange = () => {
    setOpen((prevOpen) => !prevOpen);
  };

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      isOpen={isOpen}
      onOpenChange={handleOpenChange}
    >
      <Item key="apples">Apples</Item>
      <Item key="bananas">Bananas</Item>
      <Item key="grapes">Grapes</Item>
      <Item key="oranges">Oranges</Item>
    </MultiComboBox>
  );
}

function Example() {
  const [isOpen, setOpen] = useState(false);

  const handleOpenChange = () => {
    setOpen((prevOpen) => !prevOpen);
  };

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      isOpen={isOpen}
      onOpenChange={handleOpenChange}
    >
      <Item key="apples">Apples</Item>
      <Item key="bananas">Bananas</Item>
      <Item key="grapes">Grapes</Item>
      <Item key="oranges">Oranges</Item>
    </MultiComboBox>
  );
}

function Example() {
  const [
    isOpen,
    setOpen
  ] = useState(false);

  const handleOpenChange =
    () => {
      setOpen((
        prevOpen
      ) => !prevOpen);
    };

  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      isOpen={isOpen}
      onOpenChange={handleOpenChange}
    >
      <Item key="apples">
        Apples
      </Item>
      <Item key="bananas">
        Bananas
      </Item>
      <Item key="grapes">
        Grapes
      </Item>
      <Item key="oranges">
        Oranges
      </Item>
    </MultiComboBox>
  );
}

Clear button

The isClearable prop gives you opportunity to decide if you want to have the clear button.

function Example() {
  return (
    <MultiComboBox label='What is your favorite fruit?' isClearable={false}>
      <Item key='apples'>Apples</Item>
      <Item key='bananas'>Bananas</Item>
      <Item key='grapes'>Grapes</Item>
      <Item key='oranges'>Oranges</Item>
    </MultiComboBox>
  );
}

function Example() {
  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      isClearable={false}
    >
      <Item key="apples">Apples</Item>
      <Item key="bananas">Bananas</Item>
      <Item key="grapes">Grapes</Item>
      <Item key="oranges">Oranges</Item>
    </MultiComboBox>
  );
}

function Example() {
  return (
    <MultiComboBox
      label="What is your favorite fruit?"
      isClearable={false}
    >
      <Item key="apples">
        Apples
      </Item>
      <Item key="bananas">
        Bananas
      </Item>
      <Item key="grapes">
        Grapes
      </Item>
      <Item key="oranges">
        Oranges
      </Item>
    </MultiComboBox>
  );
}

Accessibility

For enhanced mobile device accessibility, the MultiComboBox component exchanges the default Overlay component to a Tray component. For more details on this component, please consult the Tray component docs.

In order to support internationalization, provide a localized string to the label or aria-label prop.

API