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​
Download Open in Playground Edit
Properties​
Description Defines the value of the component.Note: The property is updated upon typing. Type string
Default ""
noTypeahead​
Description Defines whether the value will be autcompleted to match an item Type boolean
Default 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
Default ""
allowCustomValues​
Description Defines if the user input will be prevented, if no matching item has been found Type boolean
Default false
disabled​
Description Defines whether the component is in disabled state.Note: A disabled component is completely noninteractive. Type boolean
Default false
valueState​
Description Defines the value state of the component. Type "None" | "Success" | "Warning" | "Error" | "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 boolean
Default false
required​
Description Defines whether the component is required. Type boolean
Default 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 boolean
Default false Since 1.20.1
accessibleName​
Description Defines the accessible ARIA name of the component. Type string
Default "" Since 1.4.0
accessibleNameRef​
Description Receives id(or many ids) of the elements that label the component. Type string
Default "" Since 1.4.0
showSelectAll​
Description Determines if the select all checkbox is visible on top of suggestions. Type boolean
Default false
Description Indicates whether the dropdown is open. True if the dropdown is open, false otherwise. Type boolean
Default 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
, Warning
or Error
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 CustomEvent
Description Fired when the value of the component changes at each keystroke or clear icon is pressed. Type CustomEvent
open-change​
Description Fired when the dropdown is opened or closed. Type CustomEvent
Since 1.0.0-rc.5
selection-change​
Description Fired when selection is changed by user interaction. Type CustomEvent<MultiComboBoxSelectionChangeEventDetail>
Parameters items : Array<IMultiComboBoxItem>
an array of the selected items.
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.
Download Open in Playground Edit
Custom values​
By default, typing of non-existing items is permitted.
Use allowCustomValues to allow typing values that are not present as items.
Download Open in Playground Edit
Select All Items​
When showSelectAll is enabled, "Select All" checkbox is displayed to allow users select all item at once.
Download Open in Playground Edit
Items Grouping​
The ui5-mcb-group-item can be used to implement grouping.
Download Open in Playground Edit
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.
Download Open in Playground Edit