ComboBox Typescript API

Interface

ComboBox

ComboBox is the alternate for the HTML select tag with editable option. It supports data binding, auto-complete, filtering, grouping, cascading and more.

Selector

smart-combo-box

Properties

animationAnimation

Sets or gets the animation mode. Animation is disabled when the property is set to 'none'

Default valueadvanced

autoCloseDelaynumber

Used only when dropDownOpenMode is set to 'auto'. Determines the delay before the opened drop down closes if the pointer is not over the element.

Default value100

autoCompleteAutoComplete

Determines the autocomplete mode. Auto complete modes filter the items from the dataSource and show only those that match the input.

Default valuenone

autoCompleteDelaynumber

Determines the delay before the drop down opens to show the matches from the auto complete operation. The delay is measured in miliseconds.

Default value100

autoOpenShortcutKeystring[]

Allows the user to define a custom key name ( or multiple key names) to open that popup with.

dataSourceany

Determines the data source that will be loaded to the ComboBox. The dataSource can be an array of strings/numbers or objects where the attributes represent the properties of a List Item. For example label, value, group. It can also be a callback that returns an Array of items as previously described.

disabledboolean

Enables or disables the combo box.

Default valuefalse

displayLoadingIndicatorboolean

Determines whether an indicator will appear during filtering and remote item loading.

Default valuefalse

displayMemberstring

Sets or gets the displayMember. The displayMember specifies the name of a property to display. The name is contained in the collection specified by the 'dataSource' property.

Default value"""

dropDownAppendToany

Determines the drop down parent. The drop down can be removed from the body of the element and continue to work in another container. This is usefull when one of the parents of the element doesn't allow overflowing, by settings this property to 'body' the drop down will be appended to the DOM and the popup will open/close as usual. dropDownAppendTo can be a string representing the id of an HTML element on the page or a direct reference to that element. Reseting it back to null will take the drop down back to it's original place.

dropDownButtonPositionDropDownButtonPosition

Determines the position of the drop down button.

Default valueright

dropDownHeightstring | number

Sets the height of the drop down. By default it's set to an empty string. In this case the height of the drop down is controlled by a CSS variable.

Default value

dropDownMaxHeightstring | number

Sets the maximum Height of the drop down. By default it's set to an empty string. In this case the maxHeight of the drop down is controlled by a CSS variable.

Default value

dropDownMaxWidthstring | number

Sets the maximum Width of the drop down. By default it's set to an empty string. In this case the maxWidth of the drop down is controlled by a CSS variable.

Default value

dropDownMinHeightstring | number

Sets the minimum Height of the drop down. By default it's set to an empty string. In this case the minHeight of the drop down is controlled by a CSS variable.

Default value

dropDownMinWidthstring | number

Sets the minimum Width of the drop down. By default it's set to an empty string. In this case the minWidth of the drop down is controlled by a CSS variable.

Default value

dropDownOpenModeDropDownOpenMode

Determines how the drop down is going to open.

Default valuedefault

dropDownOverlayboolean

If this property is enabled, when the element's dropdown is opened, a transparent overlay is positioned between the dropdown and the rest of the document. The purpose of the overlay is to make sure that clicking anywhere outside the popup will will target the overlay and not the DOM.

Default valuefalse

dropDownPlaceholderstring

Determines the placeholder for the drop down, displayed when there are no items in it.

Default value"No Items

dropDownPositionDropDownPosition

Determines the position of the drop down when opened.

Default valueauto

dropDownWidthstring | number

Sets the width of the drop down. By default it's set to an empty string. In this case the width of the drop down is controlled by a CSS variable.

Default value

escKeyModeComboBoxEscKeyMode

Determines the behavior of the element when Escape key is pressed.

filterableboolean

Determines whether filtering is enabled.

Default valuefalse

filterInputPlaceholderstring

Determines the placeholder for the drop down list filter input field.

Default value"

filterModeFilterMode

Determines the filtering mode of the Combo box.

Default valuestartsWithIgnoreCase

groupedboolean

If enabled, the items will be grouped by their first letter. Can't be applied if the dataSource already contains groups.

Default valuefalse

groupMemberstring

Determines which attribute from the dataSource object will be used as the group member for the items. If not set, by default 'group' property is used from the source object. groupMember is especially usefull when loading the data from a JSON file as a dataSource for the ListBox and there's a specific property that should be used to group the items.

Default value"

hintstring

Sets additional helper text below the element. The hint is visible only when the element is focused.

Default value"

horizontalScrollBarVisibilityHorizontalScrollBarVisibility

Determines the visibility of the horizontal Scroll bar inside the drop down.

Default valueauto

inputMemberstring

Represents the property name of a List item. Determines the value of the input when a ListItem is selected. Usefull in cases where the user wants to display for example the value of an item instead of it's label. By default the label is displayed in the input.

Default value"

inputPurposestring

Sets the purpose of the input and what, if any, permission the user agent has to provide automated assistance in filling out the element's input when in a form, as well as guidance to the browser as to the type of information expected in the element. This value corresponds to the standard HTML autocomplete attribute and can be set to values such as 'on', 'name', 'organization', 'street-address', etc.

Default value"off

incrementalSearchDelaynumber

IncrementalSearchDelay property specifies the time-interval in milliseconds until the previous search query is cleared. The timer starts when the user stops typing. A new query can be started only when the delay has passed.

Default value700

incrementalSearchModeSearchMode

Sets ot gets the mode of the incremental search mode. Incremental search is enabled by default. Typing while the drop down is focused starts the incremental search.

Default valuestartsWithIgnoreCase

itemHeightnumber

Sets the height for all list items. Used only when virtualization is enabled.

itemMeasureModeListItemMeasureMode

Determines the item width measuring algorithm.

Default valueauto

items{label: string, value: string}[]

A getter that returns an array of all List items inside the drop down.

Default value

itemTemplateany

The itemTemplate property is a string that represents the id of an HTMLTemplateElement in the DOM. It's used to set a customize the content of the list items.

labelstring

Sets a little text label above the element.

Default value"

loadingIndicatorPlaceholderstring

Determines the text that will be displayed next to the loading indicator when the loader is visible and it's position is top or bottom.

Default value"Loading...

loadingIndicatorPositionVerticalAlignment

Determines the position of the loading indicator.

Default valuecenter

localestring

Sets or gets the language. Used in conjunction with the property messages.

Default value"en

localizeFormatFunctionany

Callback used to customize the format of the messages that are returned from the Localization Module.

messagesany

Sets or gets an object specifying strings used in the widget that can be localized. Used in conjunction with the property locale.

Default value


"en": {

"propertyUnknownType": "'{{name}}' property is with undefined 'type' member!",

"propertyInvalidValue": "Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!",

"propertyInvalidValueType": "Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!",

"elementNotInDOM": "Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.",

"moduleUndefined": "Module is undefined.",

"missingReference": "{{elementType}}: Missing reference to {{files}}.",

"htmlTemplateNotSuported": "{{elementType}}: Browser doesn't support HTMLTemplate elements.",

"invalidTemplate": "{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM.",

"invalidNode": "{{elementType}}: Invalid parameter '{{node}}' when calling {{method}}."

}

minLengthnumber

Determines the minimum number of characters inside the input in order to trigger the autocomplete functionality

Default value2

namestring

Sets or gets the name attribute for the element. Name is used when submiting HTML forms.

Default value"

openedboolean

Determines whether the popup is opened or closed

Default valuefalse

placeholderstring

Determines the input's placeholder.

Default value"

readonlyboolean

Disables user interaction with the element.

Default valuefalse

rightToLeftboolean

Sets or gets the value indicating whether the element is aligned to support locales using right-to-left fonts.

Default valuefalse

resizeIndicatorboolean

Determines whether the resize indicator in the bottom right corner of the drop down is visible or not. This property is used in conjunction with resizeMode.

Default valuefalse

resizeModeResizeMode

Determines whether the dropDown can be resized or not. When resizing is enabled, a resize bar appears on the top/bottom side of the drop down.

selectionDisplayModeSelectionDisplayMode

Determines what will be displayed in the input.

Default valueplain

selectedIndexesnumber[]

Sets or gets the selected indexes. Selected indexes represents an array of the indexes of the items that should be selected.

selectedValuesstring[]

Sets or gets elected indexes. Selected values represents the values of the items that should be selected.

selectionModeListSelectionMode

Determines how many items can be selected.

Default valueone

sortedboolean

Determines whether the items are sorted alphabetically or not

Default valuefalse

sortDirectionstring

Determines sorting direction - ascending(asc) or descending(desc)

Default value"asc

themestring

Determines the theme for the element. Themes define the look of the elements.

Default value"

tokenTemplateany

Sets a custom content for the tokens when selectionDisplayMode is set to 'tokens'. Tokens are used only for multiple selection.

unfocusableboolean

If is set to true, the element cannot be focused.

Default valuefalse

valuestring

Sets or gets the value.

Default value"

valueMemberstring

Determines the value member of an item. Stored as value in the item object. Similar to groupMember, valueMember is especially usefull when using data from a JSON file as a dataSource for the ListBox and there's a specific property that should be used for the value the items.

Default value"""

verticalScrollBarVisibilityVerticalScrollBarVisibility

Determines the visibility of the vertical scroll bar.

Default valueauto

virtualizedboolean

Determines weather or not Virtualization is used for the Combo box. Virtualization allows a huge amount of items to be loaded to the List box while preserving the performance. For example a milion items can be loaded to the list box.

Default valuefalse

onchange((this: Window, ev: Event) => any) | null

This event is triggered when the selection is changed.

Arguments

onclose((this: Window, ev: Event) => any) | null

This event is triggered when the drop down list is closed.

Arguments

onclosing((this: Window, ev: Event) => any) | null

This event is triggered when the drop down list is about to be closed. This event allows to cancel the closing operation calling event.preventDefault() in the event handler function.

Arguments

onitemclick((this: Window, ev: Event) => any) | null

This event is triggered when an item is clicked.

Arguments

onopen((this: Window, ev: Event) => any) | null

This event is triggered when the drop down list is opened.

Arguments

onopening((this: Window, ev: Event) => any) | null

This event is triggered when the drop down list is about to be opened. This event allows to cancel the opening operation calling event.preventDefault() in the event handler function.

Arguments

onresizestart((this: Window, ev: Event) => any) | null

This event is triggered when user starts resizing the drop down.

Arguments

onresizeend((this: Window, ev: Event) => any) | null

This event is triggered when the resizing of the drop down is finished.

Arguments

onscrollbottomreached((this: Window, ev: Event) => any) | null

This event is triggered when user scrolls to the end of the dropDown list.

Arguments

onscrolltopreached((this: Window, ev: Event) => any) | null

This event is triggered when user scrolls to the start of the dropDown list.

Arguments

Methods

appendChild( node: Node): T

Arguments

nodeNode

A ListItem element that should be added to the rest of the items as the last item.

ReturnsNode

clearItems(): void

Removes all items from the drop down list.

clearSelection(): void

Unselects all items.

close(): void

Closes the dropDown list.

ensureVisible( item: HTMLElement | string): void

Ensures the desired item is visible by scrolling to it.

Arguments

itemHTMLElement | string

A list item or value of the desired item to be visible.

getItem( value: string): HTMLElement

Returns an item instance from the dropDown list.

Arguments

valuestring

The value of an item from the drop down list.

ReturnsHTMLElement

insert( position: number, item: any): void

Inserts a new item at a specified position.

Arguments

positionnumber

The position where the item must be inserted.

itemany

Describes the properties of the item that will be inserted.

insertBefore( node: Node, referenceNode: Node | null): T

Arguments

nodeNode

A ListItem element that should be added before the referenceItem in the list.

referenceNodeNode | null

A ListItem element that acts as the reference item before which a new item is about to be inserted. The referenceNode must be in the same list as the node.

ReturnsNode

open(): void

Opens the dropDown list.

removeAt( position: number): void

Removes an item at a specified position.

Arguments

positionnumber

The position of the removed item.

removeChild( node: Node): T

Arguments

nodeNode

A ListItem element that is part of the list of items inside the element.

ReturnsNode

select( item: string | HTMLElement): void

Selects an item from the dropDown list.

Arguments

itemstring | HTMLElement

A string, representing the value of the item or an HTML Element referencing an item from the list

unselect( item: string | HTMLElement): void

Unselects an item from the dropDown list.

Arguments

itemstring | HTMLElement

A string, representing the value of the item or an HTML Element referencing an item from the list

update( position: number, value: any): void

Updates an item from the dropDown list.

Arguments

positionnumber

The position where the item must be updated.

valueany

The value of the updated item.

Enums

ListItem

Defines a list item for ListBox, ComboBox, DropDownList.

Selector

smart-list-item

Properties

alternationIndexnumber

Default value-1

colorstring

Default value"

displayModeListItemDisplayMode

Default valueplain

groupedboolean

Default valuefalse

selectedboolean

Default valuefalse

valuestring

Default value"

labelstring

Default value"

detailsstring

Default value"

groupstring

Default value"

hiddenboolean

Default valuefalse

readonlyboolean

Default valuefalse

Enums

ListItemsGroup

Defines a group of list items.

Selector

smart-list-items-group

Properties

labelstring

Default value"