Multi-Select Combo Box
This component supports the same features as the regular Combo Box, such as lazy loading or allowing custom typed values.
const countries = useCountries();
return (
<MultiSelectComboBox
style={{ width: "300px" }}
label="Countries"
items={countries}
itemLabelPath="name"
itemIdPath="id"
/>
);
The overlay opens when the user clicks the field using a pointing device. Using the Up and Down arrow 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.
-
Custom Item Presentation
-
Auto Open
-
Placeholder
-
Custom Filtering
-
Popup Width, using the
--vaadin-multi-select-combo-box-overlay-width
style, instead of--vaadin-combo-box-overlay-width
Selection
This component allows selecting multiple values, each of which is displayed as a chip inside the component. When there isn’t enough space in the component to display chips for all selected values, then 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.
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:
const [selectedCountries, setSelectedCountries] = useState<Country[]>([]);
const countries = useCountries();
return (
<>
<MultiSelectComboBox
style={{ width: "300px" }}
label="Countries"
items={countries}
itemLabelPath="name"
itemIdPath="id"
onSelectedItemsChanged={({ detail: { value } }) =>
setSelectedCountries(value)
}
/>
<TextArea
readonly
label="Selected countries"
value={selectedCountries.map((c) => c.name).join(", ")}
/>
</>
);
Use the onSelectedItemsChanged
event to react to the user changing the selection.
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 of the overlay, which then shows only the selected values, instead of all of the options. This can be useful if selected values have been collapsed into the overflow chip.
Internationalization (i18n)
Multi-Select Combo Box allows localizing the following messages. These texts are only used in screen reader announcements, and can’t be observed visually.
Message | Default | Description |
---|---|---|
| "Selection cleared" | Announced by screen readers when the clear button is clicked. |
| " focused. Press Backspace to remove" | Announced by screen readers when a chip is focused. |
| " added to selection" | Announced by screen readers when an item is added to the selection. |
| " removed from selection" | Announced by screen readers when an item is removed from the selection. |
| "{count} items selected" | Announced by screen readers to inform about the total number of selected items. The string must contain a |
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.
Related Components
Component | Usage Recommendation |
---|---|
Same feature set, but for selecting a single value. | |
Scrollable inline list of options. Supports single and multi-select. | |
Serves the same purpose in a more user-friendly format, but uses more vertical space. |
Important
| You can find more information in the corresponding article on vaadin.com. |