UI5 Web Components
Search

ComboBox

v1.0.0-rc.6
@ui5/webcomponents
<ui5-combobox>

Basic Example

<ui5-combobox placeholder="Enter value">
	<ui5-cb-item text="Item 1"></ui5-cb-item>
	<ui5-cb-item text="Item 2"></ui5-cb-item>
	<ui5-cb-item text="Item 3"></ui5-cb-item>
</ui5-combobox>

<ui5-combobox value-state="Success" value="Item 1">
	<ui5-cb-item text="Item 1"></ui5-cb-item>
	<ui5-cb-item text="Item 2"></ui5-cb-item>
	<ui5-cb-item text="Item 3"></ui5-cb-item>
</ui5-combobox>

<ui5-combobox value-state="Warning" value="Item 2">
	<ui5-cb-item text="Item 1"></ui5-cb-item>
	<ui5-cb-item text="Item 2"></ui5-cb-item>
	<ui5-cb-item text="Item 3"></ui5-cb-item>
</ui5-combobox>

<ui5-combobox value-state="Error" value="Item 3">
	<ui5-cb-item text="Item 1"></ui5-cb-item>
	<ui5-cb-item text="Item 2"></ui5-cb-item>
	<ui5-cb-item text="Item 3"></ui5-cb-item>
</ui5-combobox>

Disabled and Readonly properties

<ui5-combobox value="Disabled" disabled>
	<ui5-cb-item text="Item 1"></ui5-cb-item>
	<ui5-cb-item text="Item 2"></ui5-cb-item>
	<ui5-cb-item text="Item 3"></ui5-cb-item>
</ui5-combobox>

<ui5-combobox value="Readonly" readonly>
	<ui5-cb-item text="Item 1"></ui5-cb-item>
	<ui5-cb-item text="Item 2"></ui5-cb-item>
	<ui5-cb-item text="Item 3"></ui5-cb-item>
</ui5-combobox>

Filters (StartsWithPerTerm(default), StartsWith, Contains)

<ui5-combobox placeholder="Contains" filter="Contains">
	<ui5-cb-item text="Austria"></ui5-cb-item>
	<ui5-cb-item text="Bulgaria"></ui5-cb-item>
	<ui5-cb-item text="Germany"></ui5-cb-item>
	<ui5-cb-item text="United Kingdom"></ui5-cb-item>
	<ui5-cb-item text="Kazakhstan"></ui5-cb-item>
</ui5-combobox>

ComboBox with Two-Column Layout Items

<ui5-combobox placeholder="Two-column layout">
	<ui5-cb-item text="Austria" additional-text="AT"></ui5-cb-item>
	<ui5-cb-item text="Belgium" additional-text="BE"></ui5-cb-item>
	<ui5-cb-item text="Brazil" additional-text="BR"></ui5-cb-item>
	<ui5-cb-item text="Bulgaria" additional-text="BG"></ui5-cb-item>
	<ui5-cb-item text="Canada" additional-text="CA"></ui5-cb-item>
</ui5-combobox>

ComboBox with Grouping of Items

<ui5-combobox placeholder="ComboBox with grouping of suggestions">
	<ui5-cb-group-item text="A"></ui5-cb-group-item>
	<ui5-cb-item text="Argentina"></ui5-cb-item>
	<ui5-cb-item text="Australia"></ui5-cb-item>
	<ui5-cb-item text="Austria"></ui5-cb-item>	
	<ui5-cb-group-item text="B"></ui5-cb-group-item>
	<ui5-cb-item text="Bahrain"></ui5-cb-item>
	<ui5-cb-item text="Belgium"></ui5-cb-item>
	<ui5-cb-item text="Brazil"></ui5-cb-item>
	<ui5-cb-group-item text="C"></ui5-cb-group-item>
	<ui5-cb-item text="Canada"></ui5-cb-item>
	<ui5-cb-item text="Chile"></ui5-cb-item>
</ui5-combobox>

Overview

The ui5-combobox component represents a drop-down menu with a list of the available options and a text input field to narrow down the options. It is commonly used to enable users to select an option from a predefined list.

Structure

The ui5-combobox consists of the following elements:
  • Input field - displays the selected option or a custom user entry. Users can type to narrow down the list or enter their own value.
  • Drop-down arrow - expands\collapses the option list.
  • Option list - the list of available options.

Keyboard Handling

The ui5-combobox provides advanced keyboard handling.
  • [F4], [ALT]+[UP], or [ALT]+[DOWN] - Toggles the picker.
  • [ESC] - Closes the picker, if open. If closed, cancels changes and reverts the typed in value.
  • [ENTER] or [RETURN] - If picker is open, takes over the currently selected item and closes it.
  • [DOWN] - Selects the next matching item in the picker.
  • [UP] - Selects the previous matching item in the picker.
  • [PAGEDOWN] - Moves selection down by page size (10 items by default).
  • [PAGEUP] - Moves selection up by page size (10 items by default).
  • [HOME] - If focus is in the ComboBox, moves cursor at the beginning of text. If focus is in the picker, selects the first item.
  • [END] - If focus is in the ComboBox, moves cursor at the end of text. If focus is in the picker, selects the last item.

ES6 Module Import

import "@ui5/webcomponents/dist/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
accessibleName
accessible-name
string
Defines the accessible ARIA name of the component.
since v1.0.0-rc.15
accessibleNameRef
accessible-name-ref
string
""
Receives id(or many ids) of the elements that label the component
since v1.0.0-rc.15
disabled
boolean
false
Defines whether the component is in disabled state.

Note: A disabled component is completely noninteractive.
filter
ComboBoxFilter
"StartsWithPerTerm"
Defines the filter type of the component. Available options are: StartsWithPerTerm, StartsWith, Contains and None.
loading
boolean
false
Indicates whether a loading indicator should be shown in the picker.
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.
value
string
""
Defines the value of the component.
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 input field.
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 ui5-combobox 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, focusout or an item is selected.
input
Fired when typing in input.

Note: filterValue property is updated, input is changed.
selection-change
Fired when selection is changed by user interaction
item
type: sap.ui.webc.main.IComboBoxItem
description: item to be selected.

ComboBoxItem

The ui5-cb-item represents the item for a ui5-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
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.

ComboBoxGroupItem

The ui5-cb-group-item is type of suggestion item, that can be used to split the ui5-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