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.
ES6 Module Import​
import "@ui5/webcomponents/dist/ComboBox.js";
Basic Sample​
Download Open in Playground Edit
Properties​
Description Defines the value of the component. Type string
Default ""
noTypeahead​
Description Defines whether the value will be autocompleted to match an item Type boolean
Default false Since 1.19.0
placeholder​
Description Defines a short hint intended to aid the user with data entry when the component has no value. Type string
Default ""
disabled​
Description Defines whether the component is in disabled state.Note: A disabled component is completely noninteractive. Type boolean
Default false
valueState​
Description Defines the value state of the component. Type "None" | "Success" | "Warning" | "Error" | "Information"
Default "None"
readonly​
Description Defines whether the component is read-only.Note: A read-only component is not editable, but still provides visual feedback upon user interaction. Type boolean
Default false
required​
Description Defines whether the component is required. Type boolean
Default false
loading​
Description Indicates whether a loading indicator should be shown in the picker. Type boolean
Default false
Description Defines the filter type of the component. Type "StartsWithPerTerm" | "StartsWith" | "Contains" | "None"
Default "StartsWithPerTerm"
showClearIcon​
Description Defines whether the clear icon of the combobox will be shown. Type boolean
Default false Since 1.20.1
accessibleName​
Description Defines the accessible ARIA name of the component. Type string
Default "" Since 1.0.0-rc.15
accessibleNameRef​
Description Receives id(or many ids) of the elements that label the component Type string
Default "" Since 1.0.0-rc.15
default​
Description Defines the component items. Type Array<IComboBoxItem>
valueStateMessage​
Description Defines 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
, Warning
or Error
value state. Type Array<HTMLElement>
Since 1.0.0-rc.9
Description Defines the icon to be displayed in the input field. Type Array<IIcon>
Since 1.0.0-rc.9
Description Fired when the input operation has finished by pressing Enter, focusout or an item is selected. Type CustomEvent
Description Fired when typing in input or clear icon is pressed.Note: filterValue property is updated, input is changed. Type CustomEvent
selection-change​
Description Fired when selection is changed by user interaction Type CustomEvent<ComboBoxSelectionChangeEventDetail>
Parameters item : IComboBoxItem
item to be selected.
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.
Download Open in Playground Edit
Filters​
You can choose a Filter that the items will be matched against on user input (StartsWith, Contains, etc.)
Download Open in Playground Edit
Items with additional text​
The ComboBox items can show additional text.
Download Open in Playground Edit
Items Grouping​
Grouping of items can be implented via the ui5-cb-group-item web component.
Download Open in Playground Edit
Items Text Wrapping​
The sample demonstrates how the text of the items wrap when too long.
Download Open in Playground Edit