MultiComboBox

v0.11.0

@ui5/webcomponents

<ui5-multi-combobox>

Basic MultiComboBox

<ui5-multi-combobox placeholder="Type your value">
	<ui5-mcb-item selected text="UI5"></ui5-mcb-item>
</ui5-multi-combobox>

<ui5-multi-combobox readonly value="Readonly combo">
	<ui5-mcb-item selected text="UI5"></ui5-mcb-item>
</ui5-multi-combobox>

<ui5-multi-combobox disabled value="Disabled combo">
	<ui5-mcb-item selected text="UI5"></ui5-mcb-item>
</ui5-multi-combobox>

MultiComboBox with items

<ui5-multi-combobox placeholder="Choose your countries">
	<ui5-mcb-item selected text="Argentina"></ui5-mcb-item>
	<ui5-mcb-item text="Bulgaria"></ui5-mcb-item>
	<ui5-mcb-item text="Denmark"></ui5-mcb-item>
	<ui5-mcb-item text="England"></ui5-mcb-item>
	<ui5-mcb-item text="Albania"></ui5-mcb-item>
	<ui5-mcb-item text="Morocco"></ui5-mcb-item>
	<ui5-mcb-item text="Portugal"></ui5-mcb-item>
	<ui5-mcb-item text="Germany"></ui5-mcb-item>
	<ui5-mcb-item text="Philippines"></ui5-mcb-item>
	<ui5-mcb-item text="Paraguay"></ui5-mcb-item>
</ui5-multi-combobox>

MultiComboBox with free text input

<ui5-multi-combobox placeholder="Choose your countries" allow-custom-values>
	<ui5-mcb-item text="Argentina"></ui5-mcb-item>
	<ui5-mcb-item selected text="Bulgaria"></ui5-mcb-item>
	<ui5-mcb-item text="Denmark"></ui5-mcb-item>
	<ui5-mcb-item selected text="England"></ui5-mcb-item>
	<ui5-mcb-item text="Albania"></ui5-mcb-item>
	<ui5-mcb-item text="Morocco"></ui5-mcb-item>
	<ui5-mcb-item text="Portugal"></ui5-mcb-item>
	<ui5-mcb-item selected text="Germany"></ui5-mcb-item>
	<ui5-mcb-item text="Philippines"></ui5-mcb-item>
	<ui5-mcb-item text="Paraguay"></ui5-mcb-item>
</ui5-multi-combobox>

MultiComboBox with Value State

<ui5-multi-combobox value-state="Success">
	<ui5-mcb-item text="Fortune"></ui5-mcb-item>
	<ui5-mcb-item text="Luck"></ui5-mcb-item>
	<ui5-mcb-item selected text="Success"></ui5-mcb-item>
</ui5-multi-combobox>

<ui5-multi-combobox value-state="Warning">
	<ui5-mcb-item text="Attention"></ui5-mcb-item>
	<ui5-mcb-item text="Caution"></ui5-mcb-item>
	<ui5-mcb-item selected text="Warning"></ui5-mcb-item>
</ui5-multi-combobox>

<ui5-multi-combobox value-state="Error">
	<ui5-mcb-item text="Fault"></ui5-mcb-item>
	<ui5-mcb-item selected text="Error"></ui5-mcb-item>
	<ui5-mcb-item text="Mistake"></ui5-mcb-item>
</ui5-multi-combobox>

MultiComboBox with Grouping of Items

<ui5-multi-combobox placeholder="Select a country">
	<ui5-mcb-group-item text="Asia"></ui5-mcb-group-item>
	<ui5-mcb-item text="Afghanistan"></ui5-mcb-item>
	<ui5-mcb-item text="China"></ui5-mcb-item>
	<ui5-mcb-item text="India"></ui5-mcb-item>
	<ui5-mcb-item text="Indonesia"></ui5-mcb-item>
	<ui5-mcb-group-item text="Europe"></ui5-mcb-group-item>
	<ui5-mcb-item text="Austria"></ui5-mcb-item>
	<ui5-mcb-item text="Bulgaria"></ui5-mcb-item>
	<ui5-mcb-item text="Germany"></ui5-mcb-item>
	<ui5-mcb-item text="Italy"></ui5-mcb-item>
	<ui5-mcb-group-item text="North America"></ui5-mcb-group-item>
	<ui5-mcb-item text="Canada"></ui5-mcb-item>
	<ui5-mcb-item text="Granada"></ui5-mcb-item>
	<ui5-mcb-item text="Haiti"></ui5-mcb-item>
	<ui5-mcb-item text="United States"></ui5-mcb-item>
</ui5-multi-combobox>

Overview

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.

CSS Shadow Parts

CSS Shadow Parts allow developers to style elements inside the Shadow DOM.
The ui5-multi-combobox exposes the following CSS Shadow Parts:

token-{index} - Used to style each token(where token-0 corresponds to the first item)

ES6 Module Import

import "@ui5/webcomponents/dist/MultiComboBox";

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name

Type

Default Value

Description

accessibleName
accessible-name

string

Defines the accessible ARIA name of the component.

since v1.4.0

accessibleNameRef
accessible-name-ref

string

Receives id(or many ids) of the elements that label the component.

since v1.4.0

allowCustomValues
allow-custom-values

boolean

false

Defines if the user input will be prevented, if no matching item has been found

disabled

boolean

false

Defines whether the component is in disabled state.

Note: A disabled component is completely noninteractive.

filter

string

"StartsWithPerTerm"

Defines the filter type of the component. Available options are: StartsWithPerTerm, StartsWith, Contains and None.

noTypeahead
no-typeahead

boolean

false

Defines whether the value will be autcompleted to match an item

since v1.4.0

open (readonly)

boolean

false

Indicates whether the dropdown is open. True if the dropdown is open, false otherwise.

since v1.0.0-rc.5

placeholder

string

Defines a short hint intended to aid the user with data entry when the component has no value.

readonly

boolean

false

Defines whether the component is read-only.

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

required

boolean

false

Defines whether the component is required.

since v1.0.0-rc.5

value

string

Defines the value of the component.

Note: The property is updated upon typing.

valueState
value-state

ValueState

"None"

Defines the value state of the component.

Available options are:

None
Error
Warning
Success
Information

Slots

This Element provides slot(s). This means it can display its child nodes.
Unless targeting the default slot, use the slot attribute to define the destination slot for each child.
Text, along with HTML Elements with no slot attribute, goes the the default slot.

Slot

Type

Description

default

HTMLElement [0..n]

Defines the component items.

icon

HTMLElement [0..n]

Defines the icon to be displayed in the component.

valueStateMessage

HTMLElement [0..n]

Defines the value state message that will be displayed as pop up under the component.

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.

Events

This Web Component fires semantic events upon user interaction. You can bind to these events with the standard DOM APIs, such as addEventListener.

Name

Description

change

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

input

Fired when the value of the component changes at each keystroke.

open-change

Fired when the dropdown is opened or closed.

since v1.0.0-rc.5

selection-change

Fired when selection is changed by user interaction in SingleSelect and MultiSelect modes.

items

type: Array
description: an array of the selected items.

MultiComboBoxItem

The ui5-mcb-item represents the item for a ui5-multi-combobox.

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name

Type

Default Value

Description

selected

boolean

false

Defines the selected state of the component.

additionalText
additional-text

string

Defines the additional text of the component.

since v1.0.0-rc.11

text

string

Defines the text of the component.

MultiComboBoxGroupItem

The ui5-mcb-group-item is type of suggestion item, that can be used to split the ui5-multi-combobox suggestions into groups.

Properties/Attributes

You can use both properties and attributes with the same effect. The name of each attribute is listed below the name of the property, if different.

Name

Type

Default Value

Description

text

string

Defines the text of the component.

Theme:

Morning Horizon (Light)

Evening Horizon (Dark)

Horizon High Contrast Black

Horizon High Contrast White

Quartz Light

Quartz Dark

Quartz High Contrast Black

Quartz High Contrast White

Content Density:

Cozy

Compact

Text Direction:

LTR

RTL

Apply

Cancel