ComboBox
<ui5-combobox> | Since 1.0.0-rc.6The 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.
Working with Values
The ComboBox offers two ways to work with item selection:
1. Display Text Only (using value):
<ui5-combobox value="Germany">
<ui5-cb-item text="Germany"></ui5-cb-item>
<ui5-cb-item text="France"></ui5-cb-item>
</ui5-combobox>
Use this approach when the displayed text is sufficient for your needs.
2. Unique Identifiers - Recommended (using selectedValue and item value):
<ui5-combobox value="Germany" selected-value="DE">
<ui5-cb-item text="Germany" value="DE"></ui5-cb-item>
<ui5-cb-item text="France" value="FR"></ui5-cb-item>
</ui5-combobox>
This is the recommended approach when you need to work with unique identifiers (IDs, codes) separate from display text.
The selectedValue property references the value property of the selected item.
In forms, the item's value (e.g., "DE") will be submitted instead of the display text.
Important: Do not mix the selectedValue approach with the deprecated selected property on items.
Keyboard Handling
The ui5-combobox provides advanced keyboard handling.
- [F4], [Alt]+[Up], or [Alt]+[Down] - Toggles the picker.
- [Escape] - 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.
- [Page Down] - Moves selection down by page size (10 items by default).
- [Page Up] - 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.
- [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.
ES6 Module Import
import "@ui5/webcomponents/dist/ComboBox.js";
Basic Sample
Properties
value
selectedValue
name
noTypeahead
placeholder
disabled
valueState
readonly
required
loading
filter
showClearIcon
accessibleName
accessibleNameRef
open
Slots
default
valueStateMessage
icon
Events
change
open
close
input
selection-change
Methods
No methods available for this component.
CSS Parts
No CSS parts available for this component.
CSS Custom States
No CSS custom states available for this component.
More Samples
Clear Icon
The ComboBox can show a clear icon, visble when there is a value, typed by the user. When pressed, the value gets cleared.
Filters
You can choose a Filter that the items will be matched against on user input (StartsWith, Contains, etc.)
Items with additional text
The ComboBox items can show additional text.
Items Grouping
Grouping of items can be implented via the ui5-cb-group-item web component.
Items Text Wrapping
The sample demonstrates how the text of the items wrap when too long.
Selected Value
Use the value property on items and selected-value on the ComboBox to decouple the display text from the underlying selection value.
This is useful for form submission, programmatic selection, and handling items with identical display text.
Items with Same Text but Different Values
When you have multiple items with identical display text (e.g., employees with the same name), use the value property to uniquely identify each item.
The additional-text property helps users distinguish between items visually.