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 one or more options 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.
Picker
If the ui5-combobox is focused, you can open or close the drop-down by pressing F4, ALT+UP or ALT+DOWN keys.
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
disabled
boolean
false
Defines whether ui5-combobox is in disabled state.
Note: A disabled ui5-combobox is completely uninteractive.
filter
string
"StartsWithPerTerm"
Defines the filter type of the ui5-combobox. Available options are: StartsWithPerTerm, StartsWith and Contains.
filterValue
filter-value
string
""
Defines the "live" value of the ui5-combobox.
Note: The property is updated upon typing.
Note: Initially the filter value is synced with value.
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 ui5-combobox has no value.
readonly
boolean
false
Defines whether the ui5-combobox is readonly.
Note: A read-only ui5-combobox is not editable, but still provides visual feedback upon user interaction.
required
boolean
false
Defines whether the ui5-combobox is required.
value
string
""
Defines the value of the ui5-combobox.
valueState
value-state
ValueState
"None"
Defines the value state of the ui5-combobox.
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.
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 ui5-combobox.
Note: If not specified, a default text (in the respective language) will be displayed. Note: The valueStateMessage would be displayed, when the ui5-select 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.
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 ui5-cb-item.
since v1.0.0-rc.11
text
string
""
Defines the text of the ui5-cb-item.
Theme:Quartz LightQuartz DarkQuartz High Contrast BlackQuartz High Contrast WhiteBelizeHigh Contrast BlackHigh Contrast White