The ui5-multi-combobox component consists of a list box with items and a text field allowing the user to either type a value directly into the text field, or choose from the list of existing items.
The drop-down list is used for selecting and filtering values, it enables users to select one or more options from a predefined list. The control provides an editable input field to filter the list, and a dropdown arrow to expand/collapse the list of available options.
The options in the list have checkboxes that permit multi-selection. Entered values are displayed as tokens.
Structure​
The ui5-multi-combobox consists of the following elements:
Tokenizer - a list of tokens with selected options.
Input field - displays the selected option/s as token/s. Users can type to filter the list.
Drop-down arrow - expands\collapses the option list.
Option list - the list of available options.
Keyboard Handling​
The ui5-multi-combobox provides advanced keyboard handling.
If the ui5-multi-combobox is focused,
you can open or close the drop-down by pressing [F4], [Alt] + [Up] or [Alt] + [Down] keys.
Once the drop-down is opened, you can use the UP and DOWN arrow keys
to navigate through the available options and select one by pressing the Space or Enter keys.
Left/Right arrow keys - moves the focus selection form the currently focused token to the previous/next one (if available).
Delete - deletes the token and focuses the previous token.
Backspace - deletes the token and focus the next token.
ES6 Module Import​
import "@ui5/webcomponents/dist/MultiComboBox.js";
Basic Sample​
Properties​
Description Defines the value of the component.Note: The property is updated upon typing. Type stringDefault ""
Description Determines the name by which the component will be identified upon submission in an HTML form.Note: This property is only applicable within the context of an HTML Form element. Note: When the component is used inside a form element, the value is sent as the first element in the form data, even if it's empty. Type string | undefinedDefault undefined Since 2.0.0
noTypeahead​
Description Defines whether the value will be autcompleted to match an item Type booleanDefault false Since 1.4.0
placeholder​
Description Defines a short hint intended to aid the user with data entry when the component has no value. Type string | undefinedDefault undefined
noValidation​
Description Defines if the user input will be prevented, if no matching item has been found Type booleanDefault false
disabled​
Description Defines whether the component is in disabled state.Note: A disabled component is completely noninteractive. Type booleanDefault false
valueState​
Description Defines the value state of the component. Type "None" | "Positive" | "Critical" | "Negative" | "Information"Default "None"
readonly​
Description Defines whether the component is read-only.Note: A read-only component is not editable, but still provides visual feedback upon user interaction. Type booleanDefault false
required​
Description Defines whether the component is required. Type booleanDefault false Since 1.0.0-rc.5
Description Defines the filter type of the component. Type "StartsWithPerTerm" | "StartsWith" | "Contains" | "None"Default "StartsWithPerTerm"
showClearIcon​
Description Defines whether the clear icon of the multi-combobox will be shown. Type booleanDefault false Since 1.20.1
accessibleName​
Description Defines the accessible ARIA name of the component. Type string | undefinedDefault undefined Since 1.4.0
accessibleNameRef​
Description Receives id(or many ids) of the elements that label the component. Type string | undefinedDefault undefined Since 1.4.0
showSelectAll​
Description Determines if the select all checkbox is visible on top of suggestions. Type booleanDefault false
Description Indicates whether the dropdown is open. True if the dropdown is open, false otherwise. Type booleanDefault false Readonly true
default​
Description Defines the component items. Type Array<IMultiComboBoxItem>
Description Defines the icon to be displayed in the component. Type Array<IIcon>Since 1.0.0-rc.9
valueStateMessage​
Description Defines the value state message that will be displayed as pop up under the component. The value state message slot should contain only one root element.Note: If not specified, a default text (in the respective language) will be displayed.Note: The valueStateMessage would be displayed, when the component is in Information, Critical or Negative value state. Type Array<HTMLElement>Since 1.0.0-rc.9
Description Fired when the input operation has finished by pressing Enter or on focusout. Type CustomEventBubbles Yes Cancelable No
Description Fired when the value of the component changes at each keystroke or clear icon is pressed. Type CustomEventBubbles Yes Cancelable No
Description Fired when the dropdown is opened. Type CustomEventSince 2.0.0 Bubbles Yes Cancelable No
Description Fired when the dropdown is closed. Type CustomEventSince 2.0.0 Bubbles Yes Cancelable No
selection-change​
Description Fired when selection is changed by user interaction. Type CustomEvent<MultiComboBoxSelectionChangeEventDetail>Parameters items : Array<IMultiComboBoxItem>Bubbles Yes Cancelable Yes - via preventDefault()
Methods​
No methods available for this component.
CSS Parts​
Name Description token-{index} Used to style each token(where token-0 corresponds to the first item)
More Samples​
Clear Icon​
The MultiComboBox can show a clear icon, visble when there is a value, typed by the user.
When pressed, the value gets cleared.
Custom values​
By default, typing of non-existing items is permitted.
Use noValidation to allow typing values that are not present as items.
Select All Items​
When showSelectAll is enabled, "Select All" checkbox is displayed to allow users select all item at once.
Items Grouping​
The ui5-mcb-item-group can be used to implement grouping.
Items Text Wrapping​
The sample demonstrates how the text of the items wrap when too long.
Note: their representation in the input field (known as token) will truncate.