Docs

Docs

Multi-Select Combo Box

Source: TypeScript / Java
Adding a combo box to a project for users to be able to make multiple selections.

Multi-Select Combo Box allows the user to choose one or more values from a filterable list of options presented in an overlay. The component supports the same features as the regular Combo Box, such as lazy loading or allowing custom typed values. This page explains how to add this component to your project and how to configure it.

Open in a
new tab
@state()
private items: Country[] = [];

protected override async firstUpdated() {
  this.items = await getCountries();
}

protected override render() {
  return html`
    <vaadin-multi-select-combo-box
      label="Countries"
      item-label-path="name"
      item-id-path="id"
      .items="${this.items}"
    ></vaadin-multi-select-combo-box>
  `;
}

The overlay opens when the user clicks the field using a pointing device. Using the Up and Downarrow keys, or typing a character — that occurs in at least one of the options — when the field is focused also opens the popup.

Common Combo Box Features

Multi-Select Combo Box supports the following features from the regular Combo Box. All the linked examples and code snippets can be applied by replacing the Combo Box with a Multi-Select Combo Box.

Selection

The component allows selecting multiple values, each of which is displayed as a chip inside the component. If there isn’t enough space in the component to display chips for all selected values, some values are collapsed into an overflow chip. The example below shows a Multi-Select Combo Box with multiple preselected values, some of which are collapsed into the overflow chip:

Open in a
new tab
<vaadin-multi-select-combo-box
  label="Countries"
  item-label-path="name"
  item-id-path="id"
  .items="${this.items}"
  .selectedItems="${this.items.slice(0, 4)}"
></vaadin-multi-select-combo-box>

When the overlay is closed, items can be removed one by one (starting with the most recently selected item) using the Backspace key. The first Backspace press moves focus to the last chip; the second press removes that chip, and the corresponding item, from the selection.

Selection Change

The following example demonstrates how to listen for selection changes:

Open in a
new tab

Use the selected-items-changed event to react to the user changing the selection.

@state()
private selectedCountries: Country[] = [];

private get selectedCountriesText(): string {
  return this.selectedCountries.map((country) => country.name).join(', ');
}

protected override render() {
  return html`
    <vaadin-horizontal-layout theme="spacing">
      <vaadin-multi-select-combo-box
        label="Countries"
        item-label-path="name"
        item-id-path="id"
        .items="${this.items}"
        .selectedItems="${this.selectedCountries}"
        @selected-items-changed="${(e: MultiSelectComboBoxSelectedItemsChangedEvent<Country>) => {
          this.selectedCountries = e.detail.value;
        }}"
      ></vaadin-multi-select-combo-box>
      <vaadin-text-area
        label="Selected Countries"
        readonly
        .value="${this.selectedCountriesText}"
      ></vaadin-text-area>
    </vaadin-horizontal-layout>
  `;
}

Read-Only

The component can be set to read-only, which prevents the user from modifying its value. A read-only Multi-Select Combo Box still allows opening the overlay, which then shows only the selected values, instead of all the options. This can be useful if selected values have been collapsed into the overflow chip.

Open in a
new tab
<vaadin-multi-select-combo-box
  label="Countries"
  item-label-path="name"
  item-id-path="id"
  .items="${this.items}"
  .selectedItems="${this.items.slice(0, 4)}"
  readonly
></vaadin-multi-select-combo-box>

Auto Expand

The component can be configured to auto-expand so as to accommodate chips for selected items. It’s possible to expand both horizontally (i.e., until max-width is reached) and vertically — in which case the field with chips wraps in multiple lines. These modes can be used together.

Open in a
new tab
@state()
private items: Country[] = [];

protected override async firstUpdated() {
  this.items = await getCountries();
}

protected override render() {
  return html`
    <vaadin-multi-select-combo-box
      label="Countries"
      item-label-path="name"
      item-id-path="id"
      .items="${this.items}"
      auto-expand-horizontally
      auto-expand-vertically
      .selectedItems="${this.items.slice(0, 4)}"
    ></vaadin-multi-select-combo-box>
  `;
}

Selected Items on Top

The component can be configured to group selected items at the top of the overlay. When the selection changes, a set of items to be shown in the top group is only updated after the overlay is closed.

Open in a
new tab
@state()
private items: Country[] = [];

protected override async firstUpdated() {
  this.items = await getCountries();
}

protected override render() {
  return html`
    <vaadin-multi-select-combo-box
      label="Countries"
      item-label-path="name"
      item-id-path="id"
      item-value-path="id"
      .items="${this.items}"
      .selectedItems="${this.items.slice(20, 23)}"
      selected-items-on-top
    ></vaadin-multi-select-combo-box>
  `;
}

Item Class Names

See Combo Box, Item Class Names. In addition to items in the overlay, custom class names also apply to chips representing selected items.

Open in a
new tab
@state()
private items = ['Apple', 'Banana', 'Orange', 'Pear'];

protected override render() {
  return html`
    <vaadin-multi-select-combo-box
      label="Fruit"
      .items="${this.items}"
      .selectedItems="${this.items.slice(0, 2)}"
      .itemClassNameGenerator="${this.classNameGenerator}"
    ></vaadin-multi-select-combo-box>
  `;
}

protected classNameGenerator(item: string): string {
  switch (item) {
    case 'Apple':
      return 'coral';
    case 'Banana':
      return 'gold';
    case 'Orange':
      return 'orange';
    case 'Pear':
      return 'yellowgreen';
    default:
      return '';
  }
}

Internationalization (i18n)

Multi-Select Combo Box allows localizing the following messages. These are only used in screen reader announcements, and can’t be observed visually.

Message Default Description

cleared

"Selection cleared"

Announced by screen readers when the clear button is clicked.

focused

" focused. Press Backspace to remove"

Announced by screen readers when a chip is focused.

selected

" added to selection"

Announced by screen readers when an item is added to the selection.

deselected

" removed from selection"

Announced by screen readers when an item is removed from the selection.

total

"{count} items selected"

Announced by screen readers to inform about the total number of selected items. The string must contain a {count} placeholder, which is replaced with the actual count of selected items by the component.

The following example demonstrates how to localize the component’s messages into German:

Open in a
new tab
private i18n: MultiSelectComboBoxI18n = {
  cleared: 'Alle Einträge entfernt',
  focused: ' ausgewählt. Drücke Rücktaste zum Entfernen',
  selected: ' hinzugefügt',
  deselected: ' entfernt',
  total: '{count} Einträge ausgewählt',
};

protected override render() {
  return html`
    <vaadin-multi-select-combo-box
      label="Länder"
      item-label-path="name"
      item-id-path="id"
      .items="${this.items}"
      .i18n="${this.i18n}"
    ></vaadin-multi-select-combo-box>
  `;
}

Best Practices

Multi-Select Combo Box supports lazy loading for large datasets. It reduces the initial load time, and consumes less bandwidth and resources.

For consistency, the default width of the Multi-Select Combo Box matches that of other input fields. You should increase the width of the component when using items with long labels, or if you expect users to select several items, to avoid collapsing selected items into the overflow chip.

Example of Increasing Component Width
<vaadin-multi-select-combo-box
  style="width: 300px"
></vaadin-multi-select-combo-box>
Component Usage Recommendations

Combo Box

Same feature set, but for selecting a single value.

List Box

Scrollable inline list of options. Supports single and multi-select.

Checkbox Group

Serves the same purpose in a more user-friendly format, but takes up more vertical space.