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""

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"
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.

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.