class sap.m.ComboBox

Control sample: sap.m.ComboBox
Visiblity: public
UX Guidelines: Combo Box
Implements:
Available since: N/A
Module: sap/m/ComboBox
Application Component: CA-UI5-CTR

A drop-down list for selecting and filtering values.

Overview

The control represents a drop-down menu with a list of the available options and a text input field to narrow down the options.

Structure

The combo-box consists of the following elements:

By setting the showSecondaryValues property, the combo box can display an additional value for each option (if there is one). Note: The typeahead feature is not available on Android devices due to a OS specific issue.

Usage

When to use:

When not to use:

Note:

The control has the following behavior regarding the selectedKey and value properties:

Responsive Behavior

This control can be a drop target.

Constructor

Constructor for a new ComboBox.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.m.ComboBox(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
filterSecondaryValues boolean false

Indicates whether the filter should check in both the text and the additionalText property of the sap.ui.core.ListItem for the suggestion.

Since: 1.46.

Visibility: public
selectedItemId string empty string

ID of the selected item.

Visibility: public
selectedKey string empty string

Key of the selected item.

Note: If duplicate keys exist, the first item matching the key is used.

Visibility: public

Borrowed Properties

Name Type Default Value Description
open boolean false

Indicates whether the picker is opened.

Visibility: public
showSecondaryValues boolean false

Indicates whether the text values of the additionalText property of a sap.ui.core.ListItem are shown.

Since: 1.60.

Visibility: public
maxWidth sap.ui.core.CSSSize 100%

Sets the maximum width of the text field.

Visibility: public
showButton boolean true

Indicates whether the dropdown downward-facing arrow button is shown.

Since: 1.38.

Visibility: public
editable boolean true

Defines whether the control can be modified by the user or not. Note: A user can tab to non-editable control, highlight it, and copy the text from it.

Since: 1.12.0.

Visibility: public
enabled boolean true

Indicates whether the user can interact with the control or not. Note: Disabled controls cannot be focused and they are out of the tab-chain.

Visibility: public
name string

The name to be used in the HTML code (for example, for HTML forms that send data to the server via submission).

Visibility: public
placeholder string

Defines a short hint intended to aid the user with data entry when the control has no value.

Visibility: public
required boolean false

Indicates that user input is required. This property is only needed for accessibility purposes when a single relationship between the field and a label (see aggregation labelFor of sap.m.Label) cannot be established (e.g. one label should label multiple fields).

Since: 1.38.4.

Visibility: public
showValueStateMessage boolean true

Indicates whether the value state message should be shown or not.

Since: 1.26.0.

Visibility: public
textAlign sap.ui.core.TextAlign Initial

Defines the horizontal alignment of the text that is shown inside the input field.

Since: 1.26.0.

Visibility: public
textDirection sap.ui.core.TextDirection Inherit

Defines the text directionality of the input field, e.g. RTL, LTR

Since: 1.28.0.

Visibility: public
value string

Defines the value of the control.

Visibility: public
valueState sap.ui.core.ValueState None

Visualizes the validation state of the control, e.g. Error, Warning, Success.

Visibility: public
valueStateText string

Defines the text that appears in the value state message pop-up. If this is not specified, a default text is shown from the resource bundle.

Since: 1.26.0.

Visibility: public
width sap.ui.core.CSSSize

Defines the width of the control.

Note: If the provided width is too small, the control gets stretched to its min width, which is needed in order for the control to be usable and well aligned.

Visibility: public

Borrowed Aggregations

Name Cardinality Type Description
items 0..n sap.ui.core.Item

Defines the items contained within this control. Note: Disabled items are not visualized in the list with the available options, however they can still be accessed through the aggregation.

formattedValueStateText 0..1 sap.m.FormattedText

Defines the formatted text that appears in the value state message pop-up. It can include links. If both valueStateText and formattedValueStateText are set - the latter is shown.

Since: 1.78.


Associations

Name Cardinality Type Description
selectedItem 0..1 sap.ui.core.Item

Sets or retrieves the selected item from the aggregation named items.


Events Overview

Event Description
change

This event is fired when the value in the text input field is changed in combination with one of the following actions:

  • The focus leaves the text input field
  • The Enter key is pressed
  • An item in the list is selected

selectionChange

This event is fired when the user types something that matches with an item in the list; it is also fired when the user presses on a list item, or when navigating via keyboard.

change

This event is fired when the value in the text input field is changed in combination with one of the following actions:

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
value string

The new value of the control

itemPressed boolean

Indicates whether the change event was caused by selecting an item in the list

selectionChange

This event is fired when the user types something that matches with an item in the list; it is also fired when the user presses on a list item, or when navigating via keyboard.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
selectedItem sap.ui.core.Item

The selected item.


Methods Overview

Method Description
_configureList

Configures the SuggestionsPopover's list.

_decoratePopupInput

Modifies the suggestions dialog input

applyShowItemsFilters

Applies Combobox specific filtering over the list items. Called within showItems method.

attachChange

Attaches event handler fnFunction to the change event of this sap.m.ComboBox.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.ComboBox itself.

This event is fired when the value in the text input field is changed in combination with one of the following actions:

  • The focus leaves the text input field
  • The Enter key is pressed
  • An item in the list is selected

attachSelectionChange

Attaches event handler fnFunction to the selectionChange event of this sap.m.ComboBox.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.ComboBox itself.

This event is fired when the user types something that matches with an item in the list; it is also fired when the user presses on a list item, or when navigating via keyboard.

clearSelection

Clears the selection.

clone

Clones the sap.m.ComboBox control.

configPicker

ComboBox picker configuration

detachChange

Detaches event handler fnFunction from the change event of this sap.m.ComboBox.

The passed function and listener object must match the ones used for event registration.

detachSelectionChange

Detaches event handler fnFunction from the selectionChange event of this sap.m.ComboBox.

The passed function and listener object must match the ones used for event registration.

exit

This method will be called when the ComboBox is being destroyed.

sap.m.ComboBox.extend

Creates a new subclass of class sap.m.ComboBox with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.ComboBoxBase.extend.

fireChange

Fires event change to attached listeners.

fireSelectionChange

Fires event selectionChange to attached listeners.

getDefaultSelectedItem

Gets the default selected item from the aggregation named items.

getFilterSecondaryValues

Gets current value of property filterSecondaryValues.

Indicates whether the filter should check in both the text and the additionalText property of the sap.ui.core.ListItem for the suggestion.

Default value is false.

sap.m.ComboBox.getMetadata

Returns a metadata object for class sap.m.ComboBox.

getSelectedItem

Gets the selected item object from the aggregation named items.

getSelectedItemId

Gets current value of property selectedItemId.

ID of the selected item.

Default value is empty string.

getSelectedKey

Gets current value of property selectedKey.

Key of the selected item.

Note: If duplicate keys exist, the first item matching the key is used.

Default value is empty string.

init

This method will be called when the ComboBox is initially created.

onAfterRenderingList

This event handler will be called after the ComboBox Picker's List is rendered.

onAfterRenderingPicker

This event handler will be called after the ComboBox's Picker is rendered.

onBeforeOpen

This event handler is called before the picker popup is opened.

onBeforeRendering

This event handler will be called before the ComboBox is rendered.

onBeforeRenderingDropdown

This event handler will be called before the ComboBox' Picker of type sap.m.Popover is rendered.

onBeforeRenderingList

This event handler will be called before the ComboBox Picker's List is rendered.

onBeforeRenderingPicker

This event handler will be called before the ComboBox's Picker is rendered.

ontap

Called when the ComboBox is clicked or tapped.

open

Opens the control's picker popup.

selectText

Sets the start and end positions of the current text selection.

setFilterSecondaryValues

Sets a new value for property filterSecondaryValues.

Indicates whether the filter should check in both the text and the additionalText property of the sap.ui.core.ListItem for the suggestion.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setSelectedItem

Sets the selectedItem association.

Default value is null.

setSelectedItemId

Sets the selectedItemId property.

Default value is an empty string "" or undefined.

setSelectedKey

Sets the selectedKey property.

Default value is an empty string "" or undefined.

synchronizeSelection

Synchronizes the selectedItem association and the selectedItemId property.

syncPickerContent

Creates picker if doesn't exist yet and sync with Control items

_configureList

Configures the SuggestionsPopover's list.

Param Type DefaultValue Description
oList sap.m.List

The list instance to be configured

_decoratePopupInput

Modifies the suggestions dialog input

Param Type DefaultValue Description
oInput sap.m.Input

The input

applyShowItemsFilters

Applies Combobox specific filtering over the list items. Called within showItems method.

attachChange

Attaches event handler fnFunction to the change event of this sap.m.ComboBox.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.ComboBox itself.

This event is fired when the value in the text input field is changed in combination with one of the following actions:

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.ComboBox itself

attachSelectionChange

Attaches event handler fnFunction to the selectionChange event of this sap.m.ComboBox.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.ComboBox itself.

This event is fired when the user types something that matches with an item in the list; it is also fired when the user presses on a list item, or when navigating via keyboard.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.ComboBox itself

clearSelection

Clears the selection.

clone

Clones the sap.m.ComboBox control.

Param Type DefaultValue Description
sIdSuffix string

Suffix to be added to the IDs of the new control and its internal objects.

configPicker

ComboBox picker configuration

Param Type DefaultValue Description
oPicker sap.m.Popover sap.m.Dialog

Picker instance

detachChange

Detaches event handler fnFunction from the change event of this sap.m.ComboBox.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachSelectionChange

Detaches event handler fnFunction from the selectionChange event of this sap.m.ComboBox.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

exit

This method will be called when the ComboBox is being destroyed.

sap.m.ComboBox.extend

Creates a new subclass of class sap.m.ComboBox with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.m.ComboBoxBase.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireChange

Fires event change to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

value string

The new value of the control

itemPressed boolean

Indicates whether the change event was caused by selecting an item in the list

fireSelectionChange

Fires event selectionChange to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

selectedItem sap.ui.core.Item

The selected item.

getDefaultSelectedItem

Gets the default selected item from the aggregation named items.

getFilterSecondaryValues

Gets current value of property filterSecondaryValues.

Indicates whether the filter should check in both the text and the additionalText property of the sap.ui.core.ListItem for the suggestion.

Default value is false.

sap.m.ComboBox.getMetadata

Returns a metadata object for class sap.m.ComboBox.

getSelectedItem

Gets the selected item object from the aggregation named items.

getSelectedItemId

Gets current value of property selectedItemId.

ID of the selected item.

Default value is empty string.

getSelectedKey

Gets current value of property selectedKey.

Key of the selected item.

Note: If duplicate keys exist, the first item matching the key is used.

Default value is empty string.

init

This method will be called when the ComboBox is initially created.

onAfterRenderingList

This event handler will be called after the ComboBox Picker's List is rendered.

onAfterRenderingPicker

This event handler will be called after the ComboBox's Picker is rendered.

onBeforeOpen

This event handler is called before the picker popup is opened.

onBeforeRendering

This event handler will be called before the ComboBox is rendered.

onBeforeRenderingDropdown

This event handler will be called before the ComboBox' Picker of type sap.m.Popover is rendered.

onBeforeRenderingList

This event handler will be called before the ComboBox Picker's List is rendered.

onBeforeRenderingPicker

This event handler will be called before the ComboBox's Picker is rendered.

ontap

Called when the ComboBox is clicked or tapped.

Param Type DefaultValue Description
oEvent jQuery.Event

The event object.

open

Opens the control's picker popup.

selectText

Sets the start and end positions of the current text selection.

Param Type DefaultValue Description
iSelectionStart int

The index of the first selected character.

iSelectionEnd int

The index of the character after the last selected character.

setFilterSecondaryValues

Sets a new value for property filterSecondaryValues.

Indicates whether the filter should check in both the text and the additionalText property of the sap.ui.core.ListItem for the suggestion.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bFilterSecondaryValues boolean false

New value for property filterSecondaryValues

setSelectedItem

Sets the selectedItem association.

Default value is null.

Param Type DefaultValue Description
vItem string sap.ui.core.Item null

New value for the selectedItem association. If an ID of a sap.ui.core.Item is given, the item with this ID becomes the selectedItem association. Alternatively, a sap.ui.core.Item instance may be given or null to clear the selection.

setSelectedItemId

Sets the selectedItemId property.

Default value is an empty string "" or undefined.

Param Type DefaultValue Description
vItem string undefined

New value for property selectedItemId. If the provided vItem is an empty string "" or undefined, the selection is cleared. If the ID has no corresponding aggregated item, the selected item is not changed.

setSelectedKey

Sets the selectedKey property.

Default value is an empty string "" or undefined.

Param Type DefaultValue Description
sKey string

New value for property selectedKey. If the provided sKey is an empty string "" or undefined, the selection is cleared. If duplicate keys exist, the first item matching the key is selected. If a key is set and no item exists with that key, the visual selection remains the same.

synchronizeSelection

Synchronizes the selectedItem association and the selectedItemId property.

syncPickerContent

Creates picker if doesn't exist yet and sync with Control items