Skip to main content

ComboBox

<ui5-combobox> | Since 1.0.0-rc.6

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.

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​

accessibleName​

DescriptionDefines the accessible ARIA name of the component.
Typestring | undefined
Defaultundefined
Since1.0.0-rc.15

accessibleNameRef​

DescriptionReceives id(or many ids) of the elements that label the component
Typestring | undefined
Defaultundefined
Since1.0.0-rc.15

disabled​

DescriptionDefines whether the component is in disabled state.
Note: A disabled component is completely noninteractive.
Typeboolean
Defaultfalse

filter​

DescriptionDefines the filter type of the component.
Type"Contains" | "None" | "StartsWith" | "StartsWithPerTerm" (value descriptions in: ComboBoxFilter)
Default"StartsWithPerTerm"

loading​

DescriptionIndicates whether a loading indicator should be shown in the picker.
Typeboolean
Defaultfalse

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

noAutoSelection​

DescriptionWhen enabled, typing does not auto-select matching items. Selection only occurs on explicit user action (arrow up/down navigation key or click).
Typeboolean
Defaultfalse

noTypeahead​

DescriptionDefines whether the value will be autocompleted to match an item
Typeboolean
Defaultfalse
Since1.19.0

open​

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

placeholder​

DescriptionDefines a short hint intended to aid the user with data entry when the component has no value.
Typestring | undefined
Defaultundefined

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

selectedValue​

DescriptionDefines the value of the selected item (references the value property of ui5-cb-item).
Use this property to work with unique identifiers (IDs, codes) instead of display text. When set, the ComboBox finds and selects the item whose value property matches this property.
Benefits:
- Select items programmatically by their unique identifier
- Handle items with identical display text but different underlying values
- Submit machine-readable values in forms (the item's value is submitted instead of the display text)
When to use selectedValue vs value:
- Recommended: Use selectedValue + item value when you need unique identifiers separate from display text (e.g., country codes "DE", "FR" with display names "Germany", "France")
- Use only the ComboBox value property when the display text itself is sufficient for your use case
Typestring | undefined
Defaultundefined
Since2.20.0

showClearIcon​

DescriptionDefines whether the clear icon of the combobox will be shown.
Typeboolean
Defaultfalse
Since1.20.1

value​

DescriptionDefines the value of the component.
Typestring
Default""

valueState​

DescriptionDefines the value state of the component.
Type"Critical" | "Information" | "Negative" | "None" | "Positive"
Default"None"

Slots​

default​

DescriptionDefines the component items.
TypeArray<IComboBoxItem>

icon​

DescriptionDefines the icon to be displayed in the input field.
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 ui5-combobox 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, focusout or an item is selected.
TypeCustomEvent
BubblesYes
CancelableNo

close​

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

input​

DescriptionFired when typing in input or clear icon is pressed.
Note: filterValue property is updated, input is changed.
TypeCustomEvent
BubblesYes
CancelableNo

open​

DescriptionFired when the dropdown is opened.
TypeCustomEvent
Since2.9.0
BubblesYes
CancelableNo

selection-change​

DescriptionFired when selection is changed by user interaction
TypeCustomEvent<ComboBoxSelectionChangeEventDetail>
Parametersitem: IComboBoxItem
item to be selected.
BubblesYes
CancelableNo

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.