Skip to main content

MultiComboBox

<ui5-multi-combobox> | Since 0.11.0

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. [Ctrl]+[Alt]+[F8] or [Command]+[Option]+[F8] - Focuses the first link in the value state message, if available. Pressing [Tab] moves the focus to the next link in the value state message, or closes the value state message if there are no more links.

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""

name

DescriptionDetermines 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.
Typestring | undefined
Defaultundefined
Since2.0.0

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 | undefined
Defaultundefined

noValidation

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" | "Positive" | "Critical" | "Negative" | "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 | undefined
Defaultundefined
Since1.4.0

accessibleNameRef

DescriptionReceives id(or many ids) of the elements that label the component.
Typestring | undefined
Defaultundefined
Since1.4.0

showSelectAll

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

open

DescriptionIndicates whether the items picker is open.
Typeboolean
Defaultfalse
Since2.9.0

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, Critical or Negative 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
BubblesYes
CancelableNo

input

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

open

DescriptionFired when the dropdown is opened.
TypeCustomEvent
Since2.0.0
BubblesNo
CancelableNo

close

DescriptionFired when the dropdown is closed.
TypeCustomEvent
Since2.0.0
BubblesNo
CancelableNo

selection-change

DescriptionFired when selection is changed by user interaction.
TypeCustomEvent<MultiComboBoxSelectionChangeEventDetail>
Parametersitems: Array<IMultiComboBoxItem>
an array of the selected items.
BubblesYes
CancelableYes - via preventDefault()

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 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.