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
evEvent
onchange((this: Window, ev: Event) => any) | null
This event is triggered when selection is changed.
Arguments
evEvent
ev.detailObject
ev.detail.addedItems - An array of List items that have been selected.
ev.detail.disabled - A flag indicating whether or not the item that caused the change event is disabled.
ev.detail.index - The index of the List item that triggered the event.
ev.detail.label - The label of the List item that triggered the event.
ev.detail.removedItems - An array of List items that have been unselected before the event was fired.
ev.detail.selected - The selected state of the List item that triggered the event. If an item was selected the value will be true and vice versa.
ev.detail.value - The value of the List item that triggered the event.
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
evEvent
ev.detailObject
ev.detail.container - The List box that an item was dragged to.
ev.detail.data - An object that contains data about the dragging operation like start position, start time, etc.
ev.detail.item - The List item that was dragged.
ev.detail.originalEvent - That original event that was fired.
ev.detail.previousContainer - The List box that an item was dragged from.
ev.detail.target - The event target.
ondragging((this: Window, ev: Event) => any) | null
This event is triggered when a List item is being dragged.
Arguments
evEvent
ev.detailObject
ev.detail.data - An object that contains data about the dragging operation like start position, start time, etc.
ev.detail.item - The List item that is being dragged. This is the item that has been clicked when initiating the drag operation
ev.detail.originalEvent - The original event that initiates the dragging operation.
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
evEvent
ev.detailObject
ev.detail.container - The List box that an item was dragged to.
ev.detail.data - An object that contains data about the dragging oepration like start position, start time, etc.
ev.detail.item - The List item that was dragged.
ev.detail.originalEvent - That original event that was fired.
ev.detail.previousContainer - The List box that an item was dragged from.
ev.detail.target - The event target.
onitemclick((this: Window, ev: Event) => any) | null
This event is triggered when an item is clicked.
Arguments
evEvent
ev.detailObject
ev.detail.disabled - Indicates whether the List item that was clicked is disabled or not.
ev.detail.index - Indicates the index of the List item that was clicked.
ev.detail.label - The label of the List item that was clicked.
ev.detail.selected - Indicates whether the List item that was clicked is selected or not.
ev.detail.value - The value of the List item that was clicked.
onitemlabelchange((this: Window, ev: Event) => any) | null
This event is triggered when an item has been edited.
Arguments
evEvent
ev.detailObject
ev.detail.selected - Indicates whether the List item is selected or not.
ev.detail.disabled - Indicates whether the List item is disabled or not.
ev.detail.index - The index of the List item that was edited.
ev.detail.label - The label of the edited List item.
ev.detail.value - The value of the List item that was edited.
onscrollbottomreached((this: Window, ev: Event) => any) | null
This event is triggered when user scrolls to the end of the list.
Arguments
evEvent
onscrolltopreached((this: Window, ev: Event) => any) | null
This event is triggered when user scrolls to the beginning of the list.
Arguments
evEvent
onswipeleft((this: Window, ev: Event) => any) | null
This event is triggered when the user swipes to the left, inside the listBox.
Arguments
evEvent
onswiperight((this: Window, ev: Event) => any) | null
This event is triggered when the user swipes to the right, inside the listBox.
Arguments
evEvent
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
Animation
None Simple AdvancedFilterMode
Contains ContainsIgnoreCase DoesNotContain DoesNotContainIgnoreCase Equals EqualsIgnoreCase StartsWith StartsWithIgnoreCase EndsWith EndsWithIgnoreCase CustomHorizontalScrollBarVisibility
Auto Disabled Hidden VisibleListBoxDropAction
Copy Move NoneListBoxSelectionChangeAction
Press ReleaseListItemMeasureMode
Auto PreciseListSelectionMode
None OneOrManyExtended ZeroOrMany OneOrMany ZeroOrOne One CheckBox RadioButtonSearchMode
Contains ContainsIgnoreCase DoesNotContain DoesNotContainIgnoreCase Equals EqualsIgnoreCase StartsWith StartsWithIgnoreCase EndsWith EndsWithIgnoreCaseVerticalAlignment
Bottom Center TopVerticalScrollBarVisibility
Auto Disabled Hidden VisibleListItem
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
ListItemsGroup
Defines a group of list items.
Selector
smart-list-items-group
Properties
labelstring
Default value"