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.

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​

DescriptionDefines the value of the component.
Typestring
Default""

selectedValue​

DescriptionDefines the selected item's value.
Use this property together with the value property on ui5-cb-item to:
- Select an item programmatically by its unique identifier
- Handle items with identical display text but different underlying values
- Submit machine-readable values in forms (the value property is submitted instead of the display text)
When set, the ComboBox finds and selects the item whose value matches this property and whose text matches the ComboBox's value (display text).
Note: This replaces the deprecated selected property on ui5-cb-item.
Typestring | undefined
Defaultundefined
Since2.19.0

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

noTypeahead​

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

placeholder​

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

disabled​

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

valueState​

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

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

loading​

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

filter​

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

showClearIcon​

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

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

open​

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

Slots​

default​

DescriptionDefines the component items.
TypeArray<IComboBoxItem>

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

icon​

DescriptionDefines the icon to be displayed in the input field.
TypeArray<IIcon>
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

open​

DescriptionFired when the dropdown is opened.
TypeCustomEvent
Since2.9.0
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

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.