ListBox Typescript API

Interface

ListBox

ListBox allows the user to select one or more items from a list.

Selector

smart-list-box

Properties

allowDragboolean

Enables or disables the ability to drag list items out of the List box. Disabled items cannot be dragged.

Default valuefalse

allowDropboolean

Enables or disables the ability to drop list items inside the target List box.

Default valuefalse

alternationCountnumber

Determines the number of color alternations in rows.

Default value0

alternationEndnumber

Determines the ending index of color alternations in rows.

Default value0

alternationStartnumber

Determines the starting index of color alternations in rows

Default value0

animationAnimation

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

Default valueadvanced

autoSortboolean

Enables or disables auto sorting. If sorted is enabled, but autoSort is false, the element will not be re-sorted automatically.

Default valuetrue

dataSourceany

Determines the data source that will be loaded to the ListBox. 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 list 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 an object property to display. The name is contained in the collection specified by the 'dataSource' property.

Default value"""

dragFeedbackFormatFunctionany

A callback function for customizing the HTML of the drag feedback. It receives one parameter - the currently dragged item.

dragOffsetnumber[]

Determines the offset of the drag feedback element from the mouse cursor when dragging an item. The first member of the array is the horizontal offset and the second one - the vertical offset.

dropActionListBoxDropAction

Determines what happens when an item is dropped.

Default valuemove

editableboolean

Determines if list items can be edited or not. If enabled, items can be edited by double clicking on a target item ( that is not disabled ) or pressing the F2 key on the keyboard.

Default valuefalse

filterableboolean

Determines whether list items can be filtered or not. If enable a filter input appears at the top of the list box.

Default valuefalse

filterCallbackany

A callback that should return a condition that will be used for custom item filtering. Used in conjunction with filterMode 'custom'

filterModeFilterMode

Determines the filtering mode.

Default valuecontainsIgnoreCase

filterInputPlaceholderstring

Determines the placeholder for the filter input field.

Default value"

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

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.

horizontalScrollBarVisibilityHorizontalScrollBarVisibility

Determines the visibility of the horizontal Scroll bar.

Default valueauto

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 List box is focused starts the incremental search.

Default valuestartsWithIgnoreCase

itemHeightnumber

Sets the height for all list box 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 ListBox items.

Default value

itemTemplateany

A string that represents the id of an HTMLTemplateElement inside the DOM or a reference to the template itself. It's used to set a custom template for the list items.

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

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

"overridingProperties": "{{elementType}}: Overriding properties {{property1}} and {{property2}} applied. The '{{property1}}' property is used by default.",

"invalidIndex": "{{elementType}}: '{{method}}' method accepts an index of type number or an Array of numbers.",

"indexOutOfBound": "{{elementType}}: Out of bound index/indexes in '{{method}}' method.",

"invalidItem": "{{elementType}}: '{{method}}' method accepts an object or an array of objects as it's second parameter.",

"invalidSettings": "{{elementType}}: '{{method}}' method accepts a string or an object as it's second parameter."

}

namestring

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

Default value"""

placeholderstring

Determines the placeholder that will be shown when the List box is empty.

Default value"No Items

readonlyboolean

Sets or gets the readonly property. If the element is readonly, users cannot interact with it.

Default valuefalse

rightToLeftboolean

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

Default valuefalse

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 depending on the selection mode.

Default valueoneOrManyExtended

selectionChangeActionListBoxSelectionChangeAction

Determines when listbox selection is achieved - on 'press' or 'release'.

Default valuerelease

sortedboolean

Determines whether the items are sorted alphabetically or not

Default valuefalse

themestring

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

Default value"

sortDirectionstring

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

Default value"asc

topVisibleIndexnumber

Ensures the item with the target index is in view as the first (top) item in the list box.

Default value-1

unfocusableboolean

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

Default valuefalse

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

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

This event is triggered when listbox binding is completed.

Arguments

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

This event is triggered when selection is changed.

Arguments

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

This event is triggered when an item is dropped. The dragging operation can be canceled by calling event.preventDefault() in the event handler function.

Arguments

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

This event is triggered when a List item is being dragged.

Arguments

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

This event is triggered when an item is dragged. The dragging operation can be canceled by 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

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

This event is triggered when an item has been edited.

Arguments

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

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

Arguments

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

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

Arguments

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

This event is triggered when the user swipes to the left, inside the listBox.

Arguments

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

This event is triggered when the user swipes to the right, inside the listBox.

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

clearSelection(): void

Unselects all items.

ensureVisible( item: HTMLElement | string): void

Ensures the target 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 listBox.

Arguments

valuestring

The value of an item from the listBox.

ReturnsHTMLElement

insert( index: number, items: any): void

Inserts a new item at a specified index.

Arguments

indexnumber

The index where the item must be inserted.

itemsany

A single item/definition or an array of List Items/definitions of list items to be inserted. The format of the item definitions is the same as the format of the dataSource property.

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

removeAt( index: number): void

Removes an item at a specified index.

Arguments

indexnumber

The index 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 | number | HTMLElement): void

Selects an item from the listBox.

Arguments

itemstring | number | 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 listBox.

Arguments

itemstring | HTMLElement

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

update( index: number, details: any): void

Updates an item from the listBox.

Arguments

indexnumber

The index of the item that is going to be updated.

detailsany

An object that contains the properties and their new values for the List item that should be updated. For example, label, value or selected attributes.

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"