Skip to main content

MultiComboBox

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.

Picker​

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.

Tokens​

  • 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​

value​

DescriptionDefines the value of the component.
Note: The property is updated upon typing.
Typestring
Default""

noTypeahead​

DescriptionDefines whether the value will be autcompleted to match an item
Typeboolean
Defaultfalse
Since1.4.0

placeholder​

DescriptionDefines a short hint intended to aid the user with data entry when the component has no value.
Typestring
Default""

allowCustomValues​

DescriptionDefines if the user input will be prevented, if no matching item has been found
Typeboolean
Defaultfalse

disabled​

DescriptionDefines whether the component is in disabled state.
Note: A disabled component is completely noninteractive.
Typeboolean
Defaultfalse

valueState​

DescriptionDefines the value state of the component.
Type"None" | "Success" | "Warning" | "Error" | "Information"
Default"None"

readonly​

DescriptionDefines whether the component is read-only.
Note: A read-only component is not editable, but still provides visual feedback upon user interaction.
Typeboolean
Defaultfalse

required​

DescriptionDefines whether the component is required.
Typeboolean
Defaultfalse
Since1.0.0-rc.5

filter​

DescriptionDefines the filter type of the component.
Type"StartsWithPerTerm" | "StartsWith" | "Contains" | "None"
Default"StartsWithPerTerm"

showClearIcon​

DescriptionDefines whether the clear icon of the multi-combobox will be shown.
Typeboolean
Defaultfalse
Since1.20.1

accessibleName​

DescriptionDefines the accessible ARIA name of the component.
Typestring
Default""
Since1.4.0

accessibleNameRef​

DescriptionReceives id(or many ids) of the elements that label the component.
Typestring
Default""
Since1.4.0

showSelectAll​

DescriptionDetermines if the select all checkbox is visible on top of suggestions.
Typeboolean
Defaultfalse

open​

DescriptionIndicates whether the dropdown is open. True if the dropdown is open, false otherwise.
Typeboolean
Defaultfalse
Readonlytrue

Slots​

default​

DescriptionDefines the component items.
TypeArray<IMultiComboBoxItem>

icon​

DescriptionDefines the icon to be displayed in the component.
TypeArray<IIcon>
Since1.0.0-rc.9

valueStateMessage​

DescriptionDefines 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.
TypeArray<HTMLElement>
Since1.0.0-rc.9

Events​

change​

DescriptionFired when the input operation has finished by pressing Enter or on focusout.
TypeCustomEvent

input​

DescriptionFired when the value of the component changes at each keystroke or clear icon is pressed.
TypeCustomEvent

open-change​

DescriptionFired when the dropdown is opened or closed.
TypeCustomEvent
Since1.0.0-rc.5

selection-change​

DescriptionFired when selection is changed by user interaction.
TypeCustomEvent<MultiComboBoxSelectionChangeEventDetail>
Parametersitems: Array<IMultiComboBoxItem>
an array of the selected items.

Methods​

No methods available for this component.

CSS Parts​

NameDescription
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 allowCustomValues 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-group-item 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.