ListBox — Smart UI JavaScript API

ListBox — Smart UI JavaScript API

On this page + Quick start

Quick start · JavaScript

Complete starter source per framework. Run the scaffold/install command first, then replace the listed files with the full code below.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>ListBox - JavaScript Quick Start</title>
  <link rel="stylesheet" href="./node_modules/smart-webcomponents/source/styles/smart.default.css" />
</head>
<body>
  <smart-list-box id="demo-listbox"></smart-list-box>

  <script type="module">
    import './node_modules/smart-webcomponents/source/modules/smart.listbox.js';

    const el = document.getElementById('demo-listbox');
    if (el) {

      el.filterable = true;
      el.selectionMode = 'zeroOrMany';
      el.dataSource = [
        { label: 'Espresso', value: 'espresso', group: 'Hot' },
        { label: 'Latte', value: 'latte', group: 'Hot' },
        { label: 'Iced Coffee', value: 'iced-coffee', group: 'Cold' },
        { label: 'Lemonade', value: 'lemonade', group: 'Cold' }
      ];
      el.grouped = true;
      el.selectedIndexes = [1];

      el.addEventListener('change', (event) => console.log('change:', event.detail || event));
    }
  </script>
</body>
</html>
For AI tooling

Developer Quick Reference

Component: ListBox   Framework: JavaScript   Selector: smart-list-box

API counts: 52 properties, 16 methods, 11 events

Common properties: 0, 1, 2, 3, 4, 5

Common methods: appendChild(), add(), clearItems(), clearSelection(), dataBind(), ensureVisible()

Common events: bindingComplete, change, dragEnd, dragging, dragStart, itemClick

Module hint: smart-webcomponents/source/modules/smart.listbox.js

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

Class

ListBox
ListItem
ListItemsGroup

ListBox

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

Selector

smart-list-box

Quick picks

changedataSourcedisableditemsvalue

Properties

AallowDragControls whether users can drag items out of the List box. When enabled, users can drag and move list items, except for those marked as disabled. Disabled items remain fixed and cannot be dragged or moved by the user.
AallowDropControls whether users can drag and drop list items into the target ListBox. When enabled, items can be dropped into the ListBox; when disabled, dropping items is not permitted.
AalternationCountSpecifies how many times the row colors alternate, controlling the pattern and frequency of color changes applied to rows in a table or list. This helps customize the visual distinction between adjacent rows.
AalternationEndSpecifies the last row index up to which alternating row colors are applied. Rows after this index will no longer display color alternations.
AalternationStartSpecifies the initial row index from which color alternation begins, determining where the alternating row colors pattern is applied in the table.
AanimationSpecifies the animation mode for the element. You can retrieve the current animation mode or set a new one by assigning a value to this property. When set to 'none', all animations are disabled. To enable different animation effects, assign one of the supported animation mode values other than 'none'.
AautoSortControls whether automatic sorting is performed. When autoSort is set to true, the element will automatically re-sort itself whenever its data changes. If sorted is enabled but autoSort is set to false, the element will only be sorted once (typically on initialization) and will not automatically update its order in response to subsequent data changes.
DdataSourceSpecifies the source of data to populate the ListBox. The dataSource can be provided in several formats:- An array of strings or numbers, where each item represents a single ListBox entry.- An array of objects, where each object defines the properties of a ListBox item, such as label (the displayed text), value (the underlying value), and group (used for grouping items).- A callback function that returns an array of items in either of the formats described above.Using these options, you can flexibly supply data from static arrays or dynamically generate the list items as needed.
DdisabledDetermines whether the list box is active and can be interacted with by the user. When enabled, users can select items from the list box; when disabled, the list box appears grayed out and does not respond to user input.
DdisplayLoadingIndicatorSpecifies whether a visual indicator (such as a loading spinner or progress bar) will be displayed while filtering data or loading items from a remote source.
DdisplayMemberDefines or retrieves the displayMember property, which specifies the name of the object property to be shown in the UI for each item in the data source. The specified name should match a key present in the objects within the collection assigned to the 'dataSource' property. This allows you to control which property value is displayed for each item when rendering data-bound lists or dropdowns.
DdragFeedbackFormatFunctionA callback function that allows you to customize the HTML markup displayed as visual feedback while an item is being dragged. This function receives a single parameter representing the item currently being dragged, enabling you to tailor the appearance of the drag feedback element based on its properties or content.
DdragOffsetSpecifies the position offset of the drag feedback element relative to the mouse cursor during a drag operation. This property takes an array with two values: the first value sets the horizontal offset (in pixels), and the second value sets the vertical offset (in pixels). These offsets determine how far the feedback element is displayed from the cursor while dragging an item.
DdropActionSpecifies the actions or behavior that are triggered when an item is released or dropped during a drag-and-drop operation. This may include updating the interface, modifying data structures, or invoking specific callback functions associated with the drop event.
EeditableSpecifies whether list items are editable. When this option is enabled, users can modify items in the list by either double-clicking on a non-disabled item or by selecting the item and pressing the F2 key. Disabled items remain uneditable regardless of this setting.
FfilterableSpecifies whether users can filter the items in the list. When enabled, a filter input field appears at the top of the list box, allowing users to quickly search and narrow down the displayed items based on their input. If disabled, the entire list is shown without any filtering option.
FfilterCallbackA callback function that must return a condition (typically a boolean value) used to determine whether each item should be included when filtering the list. This function is called for every item and is intended for use when the filterMode is set to 'custom', allowing you to define your own filtering logic beyond the default behavior.
FfilterInputPlaceholderSpecifies the placeholder text that appears inside the filter input field, guiding users on what to enter or search for.
FfilterModeSpecifies which filtering mode is applied to the data set, controlling how items are included or excluded based on defined criteria.
GgroupedWhen enabled, this option organizes the items into groups based on the first letter of each item's value. Note: This setting is incompatible with data sources that are already grouped; it can only be used when the dataSource does not contain predefined groupings.
GgroupMemberSpecifies the property name within the dataSource object that will be used to group the items in the ListBox. If this property is not set, the component defaults to using the 'group' attribute from each data item for grouping purposes. The groupMember property is particularly useful when loading data from a JSON file as the dataSource and you need to group items based on a specific custom property, rather than the default 'group' property. This allows for flexible and customized grouping behavior based on the structure of your data.
HhorizontalScrollBarVisibilityControls whether the horizontal scroll bar is displayed, allowing users to scroll content left and right when it overflows the container.
IincrementalSearchDelayThe 'IncrementalSearchDelay' property defines the amount of time, in milliseconds, that the system waits after the user stops typing before clearing the previous search query. This delay timer begins as soon as the user ceases input. Only after the specified delay has fully elapsed will the previous search query be reset, allowing a new search query to be initiated. This property helps control the responsiveness of incremental search operations, preventing premature query resets while the user is still entering input.
IincrementalSearchModeSets or retrieves the current incremental search mode. By default, incremental search is enabled, allowing users to begin searching by typing while the ListBox is focused. This mode enables real-time filtering or selection as the user types, making it easier to quickly find items in the list.
IitemHeightSpecifies the height, in pixels, for each item within the list box when virtualization is enabled. This property is required for correct rendering and performance optimizations during virtualization. It ensures each list item is allocated sufficient space and enables efficient scrolling and item measurement.
IitemMeasureModeSpecifies the algorithm used to calculate the width of each item. This setting determines how the item width is measured, such as using fixed values, automatic sizing based on content, or percentage-based calculations.
IitemsA read-only property that retrieves an array containing all the items currently present in the ListBox. Each element in the array represents a distinct item from the ListBox, preserving their order as displayed.
IitemTemplateA string specifying either the ID of an HTMLTemplateElement present in the DOM or a direct reference to the template element itself. This property allows you to define a custom template for rendering individual list items, enabling flexible and reusable item layouts within the component.
LloadingIndicatorPlaceholderSpecifies the text to be displayed alongside the loading indicator when the loader is visible and positioned at either the top or bottom of the component. This text provides contextual feedback to users during loading operations.
LloadingIndicatorPositionSpecifies the placement of the loading indicator within the user interface, such as at the top, center, or bottom of the container or screen. This property controls where the loading spinner or progress bar will appear while content is being loaded.
LlocaleSpecifies or retrieves the language code to be used for message localization. This property determines which set of messages from the messages object will be displayed, enabling support for multiple languages and dynamic language switching in your application.
LlocalizeFormatFunctionA callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify how localized messages are structured or displayed before they are rendered to the user.
MmessagesDefines or retrieves an object containing localized strings used throughout the widget’s user interface. This allows you to customize all display text and messages according to different languages or regions. Typically used together with the language property to support internationalization and provide translations for various UI elements.
NnameSets or retrieves the value of the element's name attribute. The name attribute identifies the element when submitting an HTML form, allowing its value to be included in the form data sent to the server. This is essential for processing form fields on the server-side.
PplaceholderSpecifies the placeholder text that will be displayed in the List box when there are no available items to show. This text provides guidance or information to the user when the List box is empty.
RreadonlySets or retrieves the readonly property of the element. When the readonly property is set to true, the element becomes non-editable—users can view its content but cannot modify it. This property is commonly used with input and textarea elements to prevent user interaction while still displaying the field’s value.
RrightToLeftSpecifies or retrieves a value that determines whether the element’s text direction is set to right-to-left (RTL) alignment, enabling proper display and support for languages and locales that use right-to-left scripts, such as Arabic or Hebrew.
SselectAllControls whether the select all item is displayed when Checkboxes are enabled.
SselectedIndexesGets or sets the selected indexes. The selected indexes property is an array containing the numerical indexes of the items that are currently selected. Assigning an array of indexes will update the selection to match those items; retrieving this property returns the array of currently selected item indexes.
SselectedValuesSets or retrieves the selected indexes. The selected values correspond to the values of the items that are currently selected. When setting, provide an array of indexes or values to specify which items should be marked as selected; when getting, this returns the values associated with the selected items.
SselectionChangeActionSpecifies the user interaction event that triggers the selection of a listbox item: either when the item is initially pressed (‘press’) or when the user releases the press (‘release’). Choosing ‘press’ selects the item on mouse down or touch start, while ‘release’ selects it on mouse up or touch end. This setting controls how and when the user’s selection action is registered.
SselectionModeSpecifies the maximum number of items that a user can select, based on the current selection mode (e.g., single, multiple, or none). This setting controls and restricts selection behavior within the interface.
SsortDirectionSpecifies the sorting order for the data. Accepts either 'asc' for ascending order (from lowest to highest) or 'desc' for descending order (from highest to lowest).
SsortedSpecifies whether the items should be automatically arranged in alphabetical order. If set to true, the items will be displayed from A to Z (or according to the selected locale’s alphabetical rules); if false, items will retain their original order.
TthemeSpecifies the visual theme applied to the element. Themes control the overall appearance, including colors, fonts, spacing, and other stylistic properties that define the element's look and feel. Choosing a theme ensures consistency and enhances the user interface design across the application.
TtopVisibleIndexScrolls the list box so that the item at the specified index appears as the first (topmost) visible item, ensuring it is fully in view at the top of the list.
UunfocusableWhen set to true, this property prevents the element from receiving keyboard focus, meaning users will not be able to select the element using the keyboard (e.g., via the Tab key) or by programmatic focus methods.
UunlockKeyGets or sets the unlockKey property, a unique code required to unlock access to the product. This key is used for product activation or to enable restricted features.
VvalueGets or sets the current selection value(s). This property returns an array of objects, where each object represents a selected option with the following structure: { label: string, value: any }. The 'label' is the display text shown to users, and 'value' holds the corresponding data for that option. Return type: { label: string, value: any }[].
VvalueMemberDetermines which property of each item object should be used as the item's value. The specified property is stored as the value in the item object. Similar to groupMember, the valueMember property is particularly useful when binding data from a JSON file as a dataSource for the ListBox, allowing you to designate a specific field to serve as the value for each item. This is helpful when your data objects contain multiple properties, and you want to control exactly which one will represent the underlying value of each ListBox entry.
VverticalScrollBarVisibilityControls whether the vertical scroll bar is displayed, allowing users to scroll through content vertically when it overflows the container. This setting can be used to show, hide, or automatically display the scroll bar based on the content size.
VvirtualizedSpecifies whether virtualization is enabled for the ListBox. When virtualization is enabled, the ListBox renders only the visible items in the UI, instead of generating UI elements for every item in the collection. This significantly improves performance and reduces memory usage, especially when working with large data sets (e.g., displaying one million items). Virtualization ensures smooth scrolling and responsiveness, even with a vast number of items in the ListBox.
items.label
items.value

Events

BbindingCompleteThis event is triggered after the listbox has successfully finished binding its data source. At this point, all data items have been loaded and rendered in the listbox, making it ready for user interaction or further programmatic manipulation. Use this event to perform actions that depend on the completion of data binding, such as customizing item appearance, enabling controls, or initiating additional data processing.
CchangeThis event is triggered whenever the user changes the current selection, such as when they select a different item from a list, dropdown, or any selectable element. It allows developers to respond dynamically to user input by detecting and handling selection changes in real time.
DdragEndThis event is fired when a user drops a draggable item onto a valid drop target. Within the event handler, you can call event.preventDefault() to cancel the default drop behavior, which allows you to define custom handling logic for the dropped item. This gives you full control over what should happen when an item is released on the target element.
DdraggingThis event is triggered whenever a user starts dragging a list item, providing an opportunity to handle custom logic—such as updating the UI or managing the item's state—during the drag operation.
DdragStartThis event is triggered whenever a user initiates and performs a drag action on an item. Within the event handler, you can call event.preventDefault() to cancel or prevent the default drag behavior. This allows you to override the standard dragging operation and implement custom drag-and-drop functionality as needed.
IitemClickThis event is triggered whenever a user clicks on an item within the component. It provides detailed information about the clicked item, such as its identifier and relevant data, enabling you to implement custom logic in response to user interactions.
IitemLabelChangeThis event is triggered immediately after an item has been modified and the changes have been saved. It allows you to respond to updates or modifications made to an item's data.
SscrollBottomReachedThis event is triggered when the user scrolls to the bottom of the list, indicating that the end of the available items has been reached. It can be used to load additional data or perform actions when no more items are visible in the current list view.
SscrollTopReachedThis event is triggered when the user scrolls to the very top of the list, indicating that the first item in the list is visible or has been reached. It can be used to implement features such as loading previous items, displaying a refresh indicator, or updating the UI when the user navigates to the start of the list.
SswipeleftThis event is triggered when the user performs a leftward swipe gesture within the boundaries of the listBox component. It can be used to initiate actions such as revealing additional options, deleting a list item, or any other behavior that should occur in response to a left swipe inside the listBox.
SswiperightThis event is triggered when the user performs a rightward swipe gesture within the boundaries of the listBox component. It detects intentional swipe actions to the right, allowing developers to respond to user navigation or interaction within the listBox. The event will only fire if the swipe is initiated and completed inside the listBox area.

Methods

AaddAdds one or more new items to the collection. This operation updates the data set by appending the provided item(s), making them available for future retrieval or processing.
CclearItemsClears all items from the listBox, effectively removing every entry and leaving the listBox empty. This operation does not delete the listBox itself, only its contents.
CclearSelectionDeselects all currently selected items, ensuring that no items remain selected within the list or interface.
DdataBindBinds the latest data from the data source to the component, ensuring the user interface reflects current information. This method can be called to refresh or update the displayed data whenever the data source changes.
EensureVisibleScrolls the container so that the target item is brought into view, ensuring it is fully visible to the user within the viewport or scrollable area.
GgetItemReturns a specific item instance from the listBox based on the provided index or selection criteria. The returned object represents the selected item and includes its associated properties and methods for further manipulation.
GgetItemsReturns an array containing all items currently present in the ListBox component. Each item in the array represents an individual entry within the ListBox, typically as an object with relevant properties such as value, label, and any other associated data. This allows developers to access, display, or manipulate the full set of ListBox options programmatically.
GgetSelectedValuesReturns an array of the selected values.
IinsertInserts a new item into the collection at the specified index, shifting existing items at and after that position one place to the right. The index determines the position in the array or list where the new item will be placed.
RremoveAtRemoves the item located at the specified index from the collection or array. The operation shifts all subsequent items one position to the left, effectively reducing the total number of items by one. The specified index must be within the valid range; otherwise, an error may occur.
SselectSelects a specific item from the ListBox component by programmatically highlighting or activating it, allowing for interaction as if the user had manually chosen the item from the list.
UunselectRemoves the selection from a specified item in the listBox component, ensuring that the item is no longer highlighted or considered selected by the application.
UupdateUpdates the properties or content of a specific item within the listBox control. This operation identifies the targeted item based on its index or unique identifier and applies the specified changes, ensuring the listBox reflects the latest data or state.

Properties

allowDragControls whether users can drag items out of the List box. When enabled, users can drag and move list items, except for those marked as disabled. Disabled items remain fixed and cannot be dragged or moved by the user.boolean

Controls whether users can drag items out of the List box. When enabled, users can drag and move list items, except for those marked as disabled. Disabled items remain fixed and cannot be dragged or moved by the user.

Default value

false
Try a demo showcasing the allowDrag property.

Examples

Markup and runtime examples for allowDrag:

HTML attribute:

<smart-list-box allow-drag></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.allowDrag = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const allowDrag = el.allowDrag;

allowDropControls whether users can drag and drop list items into the target ListBox. When enabled, items can be dropped into the ListBox; when disabled, dropping items is not permitted.boolean

Controls whether users can drag and drop list items into the target ListBox. When enabled, items can be dropped into the ListBox; when disabled, dropping items is not permitted.

Default value

false
Try a demo showcasing the allowDrop property.

Examples

Markup and runtime examples for allowDrop:

HTML attribute:

<smart-list-box allow-drop></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.allowDrop = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const allowDrop = el.allowDrop;

alternationCountSpecifies how many times the row colors alternate, controlling the pattern and frequency of color changes applied to rows in a table or list. This helps customize the visual distinction between adjacent rows.number

Specifies how many times the row colors alternate, controlling the pattern and frequency of color changes applied to rows in a table or list. This helps customize the visual distinction between adjacent rows.

Default value

0

Examples

Markup and runtime examples for alternationCount:

HTML:

<smart-list-box alternation-count="true"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.alternationCount = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const alternationCount = el.alternationCount;

alternationEndSpecifies the last row index up to which alternating row colors are applied. Rows after this index will no longer display color alternations.number

Specifies the last row index up to which alternating row colors are applied. Rows after this index will no longer display color alternations.

Default value

0

Examples

Markup and runtime examples for alternationEnd:

HTML:

<smart-list-box alternation-end="true"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.alternationEnd = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const alternationEnd = el.alternationEnd;

alternationStartSpecifies the initial row index from which color alternation begins, determining where the alternating row colors pattern is applied in the table.number

Specifies the initial row index from which color alternation begins, determining where the alternating row colors pattern is applied in the table.

Default value

0

Examples

Markup and runtime examples for alternationStart:

HTML:

<smart-list-box alternation-start="true"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.alternationStart = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const alternationStart = el.alternationStart;

animationSpecifies the animation mode for the element. You can retrieve the current animation mode or set a new one by assigning a value to this property. When set to 'none', all animations are disabled. To enable different animation effects, assign one of the supported animation mode values other than 'none'."none" | "simple" | "advanced"

Specifies the animation mode for the element. You can retrieve the current animation mode or set a new one by assigning a value to this property. When set to 'none', all animations are disabled. To enable different animation effects, assign one of the supported animation mode values other than 'none'.

Allowed Values

  • "none" - animation is disabled
  • "simple" - ripple animation is disabled
  • "advanced" - all animations are enabled

Default value

"advanced"

Examples

Markup and runtime examples for animation:

HTML:

<smart-list-box animation="none"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.animation = "simple";

Read the current value:

const el = document.querySelector('smart-list-box');
const animation = el.animation;

autoSortControls whether automatic sorting is performed. When autoSort is set to true, the element will automatically re-sort itself whenever its data changes. If sorted is enabled but autoSort is set to false, the element will only be sorted once (typically on initialization) and will not automatically update its order in response to subsequent data changes.boolean

Controls whether automatic sorting is performed. When autoSort is set to true, the element will automatically re-sort itself whenever its data changes. If sorted is enabled but autoSort is set to false, the element will only be sorted once (typically on initialization) and will not automatically update its order in response to subsequent data changes.

Default value

true

Examples

Markup and runtime examples for autoSort:

HTML attribute:

<smart-list-box auto-sort></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.autoSort = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const autoSort = el.autoSort;

dataSourceSpecifies the source of data to populate the ListBox. The dataSource can be provided in several formats:- An array of strings or numbers, where each item represents a single ListBox entry.- An array of objects, where each object defines the properties of a ListBox item, such as label (the displayed text), value (the underlying value), and group (used for grouping items).- A callback function that returns an array of items in either of the formats described above.Using these options, you can flexibly supply data from static arrays or dynamically generate the list items as needed.any

Specifies the source of data to populate the ListBox. The dataSource can be provided in several formats:

- An array of strings or numbers, where each item represents a single ListBox entry.
- An array of objects, where each object defines the properties of a ListBox item, such as label (the displayed text), value (the underlying value), and group (used for grouping items).
- A callback function that returns an array of items in either of the formats described above.

Using these options, you can flexibly supply data from static arrays or dynamically generate the list items as needed.

Try a demo showcasing the dataSource property.

Examples

Markup and runtime examples for dataSource:

HTML:

<smart-list-box data-source="["item 1", "item 2"]"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.dataSource = ["new item 1", "new item 2"];

Read the current value:

const el = document.querySelector('smart-list-box');
const dataSource = el.dataSource;

disabledDetermines whether the list box is active and can be interacted with by the user. When enabled, users can select items from the list box; when disabled, the list box appears grayed out and does not respond to user input.boolean

Determines whether the list box is active and can be interacted with by the user. When enabled, users can select items from the list box; when disabled, the list box appears grayed out and does not respond to user input.

Default value

false
Try a demo showcasing the disabled property.

Examples

Markup and runtime examples for disabled:

HTML attribute:

<smart-list-box disabled></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.disabled = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const disabled = el.disabled;

displayLoadingIndicatorSpecifies whether a visual indicator (such as a loading spinner or progress bar) will be displayed while filtering data or loading items from a remote source.boolean

Specifies whether a visual indicator (such as a loading spinner or progress bar) will be displayed while filtering data or loading items from a remote source.

Default value

false
Try a demo showcasing the displayLoadingIndicator property.

Examples

Markup and runtime examples for displayLoadingIndicator:

HTML attribute:

<smart-list-box display-loading-indicator></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.displayLoadingIndicator = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const displayLoadingIndicator = el.displayLoadingIndicator;

displayMemberDefines or retrieves the displayMember property, which specifies the name of the object property to be shown in the UI for each item in the data source. The specified name should match a key present in the objects within the collection assigned to the 'dataSource' property. This allows you to control which property value is displayed for each item when rendering data-bound lists or dropdowns.string

Defines or retrieves the displayMember property, which specifies the name of the object property to be shown in the UI for each item in the data source. The specified name should match a key present in the objects within the collection assigned to the 'dataSource' property. This allows you to control which property value is displayed for each item when rendering data-bound lists or dropdowns.

Default value

""""
Try a demo showcasing the displayMember property.

Examples

Markup and runtime examples for displayMember:

HTML:

<smart-list-box display-member="label"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.displayMember = "name";

Read the current value:

const el = document.querySelector('smart-list-box');
const displayMember = el.displayMember;

dragFeedbackFormatFunctionA callback function that allows you to customize the HTML markup displayed as visual feedback while an item is being dragged. This function receives a single parameter representing the item currently being dragged, enabling you to tailor the appearance of the drag feedback element based on its properties or content.function | null

A callback function that allows you to customize the HTML markup displayed as visual feedback while an item is being dragged. This function receives a single parameter representing the item currently being dragged, enabling you to tailor the appearance of the drag feedback element based on its properties or content.

Examples

Markup and runtime examples for dragFeedbackFormatFunction:

HTML:

<smart-list-box drag-feedback-format-function="dragFeedbackFormatFunction"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.dragFeedbackFormatFunction = "function dragFeedbackFormatFunction(draggedItem) { return 'Dragging: ' + draggedItem.label; }";

Read the current value:

const el = document.querySelector('smart-list-box');
const dragFeedbackFormatFunction = el.dragFeedbackFormatFunction;

dragOffsetSpecifies the position offset of the drag feedback element relative to the mouse cursor during a drag operation. This property takes an array with two values: the first value sets the horizontal offset (in pixels), and the second value sets the vertical offset (in pixels). These offsets determine how far the feedback element is displayed from the cursor while dragging an item. number[]

Specifies the position offset of the drag feedback element relative to the mouse cursor during a drag operation. This property takes an array with two values: the first value sets the horizontal offset (in pixels), and the second value sets the vertical offset (in pixels). These offsets determine how far the feedback element is displayed from the cursor while dragging an item.

Examples

Markup and runtime examples for dragOffset:

HTML:

<smart-list-box drag-offset="[0, 0]"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.dragOffset = [-60, 20];

Read the current value:

const el = document.querySelector('smart-list-box');
const dragOffset = el.dragOffset;

dropActionSpecifies the actions or behavior that are triggered when an item is released or dropped during a drag-and-drop operation. This may include updating the interface, modifying data structures, or invoking specific callback functions associated with the drop event."copy" | "move" | "none"

Specifies the actions or behavior that are triggered when an item is released or dropped during a drag-and-drop operation. This may include updating the interface, modifying data structures, or invoking specific callback functions associated with the drop event.

Allowed Values

  • "copy" - Creates a copy of the dragged item and inserts it instead of the original. The original item retains it's place inside the original ListBox.
  • "move" - Moves the dragged item to the new host.
  • "none" - Nothing changes when the dragged item is dropped.

Default value

"move"

Examples

Markup and runtime examples for dropAction:

HTML:

<smart-list-box drop-action="copy"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.dropAction = "move";

Read the current value:

const el = document.querySelector('smart-list-box');
const dropAction = el.dropAction;

editableSpecifies whether list items are editable. When this option is enabled, users can modify items in the list by either double-clicking on a non-disabled item or by selecting the item and pressing the F2 key. Disabled items remain uneditable regardless of this setting.boolean

Specifies whether list items are editable. When this option is enabled, users can modify items in the list by either double-clicking on a non-disabled item or by selecting the item and pressing the F2 key. Disabled items remain uneditable regardless of this setting.

Default value

false
Try a demo showcasing the editable property.

Examples

Markup and runtime examples for editable:

HTML attribute:

<smart-list-box editable></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.editable = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const editable = el.editable;

filterableSpecifies whether users can filter the items in the list. When enabled, a filter input field appears at the top of the list box, allowing users to quickly search and narrow down the displayed items based on their input. If disabled, the entire list is shown without any filtering option.boolean

Specifies whether users can filter the items in the list. When enabled, a filter input field appears at the top of the list box, allowing users to quickly search and narrow down the displayed items based on their input. If disabled, the entire list is shown without any filtering option.

Default value

false
Try a demo showcasing the filterable property.

Examples

Markup and runtime examples for filterable:

HTML attribute:

<smart-list-box filterable></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.filterable = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const filterable = el.filterable;

filterCallbackA callback function that must return a condition (typically a boolean value) used to determine whether each item should be included when filtering the list. This function is called for every item and is intended for use when the filterMode is set to 'custom', allowing you to define your own filtering logic beyond the default behavior.function | null

A callback function that must return a condition (typically a boolean value) used to determine whether each item should be included when filtering the list. This function is called for every item and is intended for use when the filterMode is set to 'custom', allowing you to define your own filtering logic beyond the default behavior.

Try a demo showcasing the filterCallback property.

Examples

Markup and runtime examples for filterCallback:

HTML:

<smart-list-box filter-callback="function(item, searchQuery) { return item.value.toLowerCase() === searchQuery.toLowerCase() }"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.filterCallback = "function(item, searchQuery) { return item.value > 5 }";

Read the current value:

const el = document.querySelector('smart-list-box');
const filterCallback = el.filterCallback;

filterInputPlaceholderSpecifies the placeholder text that appears inside the filter input field, guiding users on what to enter or search for.string

Specifies the placeholder text that appears inside the filter input field, guiding users on what to enter or search for.

Default value

""
Try a demo showcasing the filterInputPlaceholder property.

Examples

Markup and runtime examples for filterInputPlaceholder:

HTML:

<smart-list-box filter-input-placeholder="Enter a value:"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.filterInputPlaceholder = "Awaiting entry:";

Read the current value:

const el = document.querySelector('smart-list-box');
const filterInputPlaceholder = el.filterInputPlaceholder;

filterModeSpecifies which filtering mode is applied to the data set, controlling how items are included or excluded based on defined criteria."contains" | "containsIgnoreCase" | "doesNotContain" | "doesNotContainIgnoreCase" | "equals" | "equalsIgnoreCase" | "startsWith" | "startsWithIgnoreCase" | "endsWith" | "endsWithIgnoreCase" | "custom"

Specifies which filtering mode is applied to the data set, controlling how items are included or excluded based on defined criteria.

Allowed Values

  • "contains" - displays only items with labels that contain the filter string (case sensitive)
  • "containsIgnoreCase" - displays only items with labels that contain the filter string (case insensitive)
  • "doesNotContain" - displays only items with labels that do not contain the filter string (case sensitive)
  • "doesNotContainIgnoreCase" - displays only items with labels that do not contain the filter string (case insensitive)
  • "equals" - displays only items with labels that equal the filter string (case sensitive)
  • "equalsIgnoreCase" - displays only items with labels that equal the filter string (case insensitive)
  • "startsWith" - displays only items with labels that start with the filter string (case sensitive)
  • "startsWithIgnoreCase" - displays only items with labels that start with the filter string (case insensitive)
  • "endsWith" - displays only items with labels that end with the filter string (case sensitive)
  • "endsWithIgnoreCase" - displays only items with labels that end with the filter string (case insensitive)
  • "custom" - filtering is applied according to the callback function filterCallback

Default value

"containsIgnoreCase"
Try a demo showcasing the filterMode property.

Examples

Markup and runtime examples for filterMode:

HTML:

<smart-list-box filter-mode="contains"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.filterMode = "equals";

Read the current value:

const el = document.querySelector('smart-list-box');
const filterMode = el.filterMode;

groupedWhen enabled, this option organizes the items into groups based on the first letter of each item's value. Note: This setting is incompatible with data sources that are already grouped; it can only be used when the dataSource does not contain predefined groupings.boolean

When enabled, this option organizes the items into groups based on the first letter of each item's value. Note: This setting is incompatible with data sources that are already grouped; it can only be used when the dataSource does not contain predefined groupings.

Default value

false
Try a demo showcasing the grouped property.

Examples

Markup and runtime examples for grouped:

HTML attribute:

<smart-list-box grouped></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.grouped = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const grouped = el.grouped;

groupMemberSpecifies the property name within the dataSource object that will be used to group the items in the ListBox. If this property is not set, the component defaults to using the 'group' attribute from each data item for grouping purposes. The groupMember property is particularly useful when loading data from a JSON file as the dataSource and you need to group items based on a specific custom property, rather than the default 'group' property. This allows for flexible and customized grouping behavior based on the structure of your data.string | null

Specifies the property name within the dataSource object that will be used to group the items in the ListBox. If this property is not set, the component defaults to using the 'group' attribute from each data item for grouping purposes. The groupMember property is particularly useful when loading data from a JSON file as the dataSource and you need to group items based on a specific custom property, rather than the default 'group' property. This allows for flexible and customized grouping behavior based on the structure of your data.

Try a demo showcasing the groupMember property.

Examples

Markup and runtime examples for groupMember:

HTML:

<smart-list-box group-member="group"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.groupMember = "section";

Read the current value:

const el = document.querySelector('smart-list-box');
const groupMember = el.groupMember;

horizontalScrollBarVisibilityControls whether the horizontal scroll bar is displayed, allowing users to scroll content left and right when it overflows the container."auto" | "disabled" | "hidden" | "visible"

Controls whether the horizontal scroll bar is displayed, allowing users to scroll content left and right when it overflows the container.

Allowed Values

  • "auto" - The element automatically determines whether or not the horizontal Scroll bar should be visible or not.
  • "disabled" - Disables the horizontal Scroll bar.
  • "hidden" - Hides the horizontal Scroll bar.
  • "visible" - Shows the horizontal Scroll bar even if not necessary.

Default value

"auto"

Examples

Markup and runtime examples for horizontalScrollBarVisibility:

HTML:

<smart-list-box horizontal-scroll-bar-visibility="disabled"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.horizontalScrollBarVisibility = "hidden";

Read the current value:

const el = document.querySelector('smart-list-box');
const horizontalScrollBarVisibility = el.horizontalScrollBarVisibility;

incrementalSearchDelayThe 'IncrementalSearchDelay' property defines the amount of time, in milliseconds, that the system waits after the user stops typing before clearing the previous search query. This delay timer begins as soon as the user ceases input. Only after the specified delay has fully elapsed will the previous search query be reset, allowing a new search query to be initiated. This property helps control the responsiveness of incremental search operations, preventing premature query resets while the user is still entering input.number

The 'IncrementalSearchDelay' property defines the amount of time, in milliseconds, that the system waits after the user stops typing before clearing the previous search query. This delay timer begins as soon as the user ceases input. Only after the specified delay has fully elapsed will the previous search query be reset, allowing a new search query to be initiated. This property helps control the responsiveness of incremental search operations, preventing premature query resets while the user is still entering input.

Default value

700

Examples

Markup and runtime examples for incrementalSearchDelay:

HTML:

<smart-list-box incremental-search-delay="group"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.incrementalSearchDelay = mygroup;

Read the current value:

const el = document.querySelector('smart-list-box');
const incrementalSearchDelay = el.incrementalSearchDelay;

incrementalSearchModeSets or retrieves the current incremental search mode. By default, incremental search is enabled, allowing users to begin searching by typing while the ListBox is focused. This mode enables real-time filtering or selection as the user types, making it easier to quickly find items in the list."contains" | "containsIgnoreCase" | "doesNotContain" | "doesNotContainIgnoreCase" | "equals" | "equalsIgnoreCase" | "startsWith" | "startsWithIgnoreCase" | "endsWith" | "endsWithIgnoreCase"

Sets or retrieves the current incremental search mode. By default, incremental search is enabled, allowing users to begin searching by typing while the ListBox is focused. This mode enables real-time filtering or selection as the user types, making it easier to quickly find items in the list.

Allowed Values

  • "contains" - focuses the item that contains the search query ( case sensitive)
  • "containsIgnoreCase" - focuses the item that contains the search query (case insensitive)
  • "doesNotContain" - focuses the item that does not contain the search query (case sensitive)
  • "doesNotContainIgnoreCase" - focuses the item that does not contain the search query (case insensitive)
  • "equals" - focuses the item that is equal the search query (case sensitive)
  • "equalsIgnoreCase" - focuses the item that is equal the search query (case insensitive)
  • "startsWith" - focuses the item that starts with the search query (case sensitive)
  • "startsWithIgnoreCase" - focuses the item that starts with the search query (case insensitive)
  • "endsWith" - focuses the item that ends with the search query (case sensitive)
  • "endsWithIgnoreCase" - focuses the item that starts with the search query (case insensitive)

Default value

"startsWithIgnoreCase"
Try a demo showcasing the incrementalSearchMode property.

Examples

Markup and runtime examples for incrementalSearchMode:

HTML:

<smart-list-box incremental-search-mode="contains"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.incrementalSearchMode = "endsWith";

Read the current value:

const el = document.querySelector('smart-list-box');
const incrementalSearchMode = el.incrementalSearchMode;

itemHeightSpecifies the height, in pixels, for each item within the list box when virtualization is enabled. This property is required for correct rendering and performance optimizations during virtualization. It ensures each list item is allocated sufficient space and enables efficient scrolling and item measurement.number

Specifies the height, in pixels, for each item within the list box when virtualization is enabled. This property is required for correct rendering and performance optimizations during virtualization. It ensures each list item is allocated sufficient space and enables efficient scrolling and item measurement.

Try a demo showcasing the itemHeight property.

Examples

Markup and runtime examples for itemHeight:

HTML:

<smart-list-box item-height="50"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.itemHeight = 80;

Read the current value:

const el = document.querySelector('smart-list-box');
const itemHeight = el.itemHeight;

itemMeasureModeSpecifies the algorithm used to calculate the width of each item. This setting determines how the item width is measured, such as using fixed values, automatic sizing based on content, or percentage-based calculations."auto" | "precise"

Specifies the algorithm used to calculate the width of each item. This setting determines how the item width is measured, such as using fixed values, automatic sizing based on content, or percentage-based calculations.

Allowed Values

  • "auto" - measures items based on the number of characters in their label
  • "precise" - measures items based on their actual size in the DOM; may hinder performance for large data sources

Default value

"auto"

Examples

Markup and runtime examples for itemMeasureMode:

HTML:

<smart-list-box item-measure-mode="precise"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.itemMeasureMode = "auto";

Read the current value:

const el = document.querySelector('smart-list-box');
const itemMeasureMode = el.itemMeasureMode;

itemsA read-only property that retrieves an array containing all the items currently present in the ListBox. Each element in the array represents a distinct item from the ListBox, preserving their order as displayed. {label: string, value: string}[]

A read-only property that retrieves an array containing all the items currently present in the ListBox. Each element in the array represents a distinct item from the ListBox, preserving their order as displayed.

Default value

null

Properties

labelThe label of the list item.
valueThe value of the list item.
Try a demo showcasing the items property.

labelThe label of the list item.string | null

The label of the list item.

Default value

""

Back to root property: items

Try a demo showcasing the label property.

Read the nested value:

const el = document.querySelector('smart-list-box');
const label = el.items[0].label;

valueThe value of the list item.string | null

The value of the list item.

Default value

""

Back to root property: items

Try a demo showcasing the value property.

Read the nested value:

const el = document.querySelector('smart-list-box');
const value = el.items[0].value;

itemTemplateA string specifying either the ID of an HTMLTemplateElement present in the DOM or a direct reference to the template element itself. This property allows you to define a custom template for rendering individual list items, enabling flexible and reusable item layouts within the component.any

A string specifying either the ID of an HTMLTemplateElement present in the DOM or a direct reference to the template element itself. This property allows you to define a custom template for rendering individual list items, enabling flexible and reusable item layouts within the component.

Try a demo showcasing the itemTemplate property.

Examples

Markup and runtime examples for itemTemplate:

HTML:

<smart-list-box item-template="'templateA'"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.itemTemplate = "'templateB'";

Read the current value:

const el = document.querySelector('smart-list-box');
const itemTemplate = el.itemTemplate;

loadingIndicatorPlaceholderSpecifies the text to be displayed alongside the loading indicator when the loader is visible and positioned at either the top or bottom of the component. This text provides contextual feedback to users during loading operations.string

Specifies the text to be displayed alongside the loading indicator when the loader is visible and positioned at either the top or bottom of the component. This text provides contextual feedback to users during loading operations.

Default value

"Loading..."

Examples

Markup and runtime examples for loadingIndicatorPlaceholder:

HTML:

<smart-list-box loading-indicator-placeholder="Incoming data"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.loadingIndicatorPlaceholder = "LOADING...";

Read the current value:

const el = document.querySelector('smart-list-box');
const loadingIndicatorPlaceholder = el.loadingIndicatorPlaceholder;

loadingIndicatorPositionSpecifies the placement of the loading indicator within the user interface, such as at the top, center, or bottom of the container or screen. This property controls where the loading spinner or progress bar will appear while content is being loaded."bottom" | "center" | "top"

Specifies the placement of the loading indicator within the user interface, such as at the top, center, or bottom of the container or screen. This property controls where the loading spinner or progress bar will appear while content is being loaded.

Allowed Values

  • "bottom" - Positions the loading indicator at the bottom of the List box.
  • "center" - Positions the loading indicator at the center of the List box.
  • "top" - Positions the loading indicator at the bottom of the List box.

Default value

"center"

Examples

Markup and runtime examples for loadingIndicatorPosition:

HTML:

<smart-list-box loading-indicator-position="bottom"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.loadingIndicatorPosition = "top";

Read the current value:

const el = document.querySelector('smart-list-box');
const loadingIndicatorPosition = el.loadingIndicatorPosition;

localeSpecifies or retrieves the language code to be used for message localization. This property determines which set of messages from the messages object will be displayed, enabling support for multiple languages and dynamic language switching in your application.string

Specifies or retrieves the language code to be used for message localization. This property determines which set of messages from the messages object will be displayed, enabling support for multiple languages and dynamic language switching in your application.

Default value

"en"

Examples

Markup and runtime examples for locale:

HTML:

<smart-list-box locale="de"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.locale = "fr";

Read the current value:

const el = document.querySelector('smart-list-box');
const locale = el.locale;

localizeFormatFunctionA callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify how localized messages are structured or displayed before they are rendered to the user.function | null

A callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify how localized messages are structured or displayed before they are rendered to the user.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

<smart-list-box localize-format-function="function(defaultMessage, message, messageArguments) {return '...'} "></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.localizeFormatFunction = "function(defaultMessage, message, messageArguments) {return '...'}";

Read the current value:

const el = document.querySelector('smart-list-box');
const localizeFormatFunction = el.localizeFormatFunction;

messagesDefines or retrieves an object containing localized strings used throughout the widget’s user interface. This allows you to customize all display text and messages according to different languages or regions. Typically used together with the language property to support internationalization and provide translations for various UI elements.object

Defines or retrieves an object containing localized strings used throughout the widget’s user interface. This allows you to customize all display text and messages according to different languages or regions. Typically used together with the language property to support internationalization and provide translations for various UI elements.

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

}

Examples

Markup and runtime examples for messages:

HTML:

<smart-list-box messages="{"de":{"propertyUnknownType":"Die Eigenschaft '{{name}}' hat ein nicht definiertes 'type'-Member!","propertyInvalidValue":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualValue}}, Erwarteter Wert: {{value}}!","propertyInvalidValueType":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualType}}, Erwarteter Wert: {{type}}!","elementNotInDOM":"Element existiert nicht in DOM! Bitte fugen Sie das Element zum DOM hinzu, bevor Sie eine Methode aufrufen.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser unterstutzt keine HTMLTemplate-Elemente.","invalidTemplate":"{{elementType}}: '{{property}}' Die Eigenschaft akzeptiert eine Zeichenfolge, die mit der ID eines HTMLTemplate-Elements aus dem DOM ubereinstimmen muss.","overridingProperties":"{{elementType}}: Uberschreiben der Eigenschaften {{property1}} und {{property2}} angewendet. Die Eigenschaft '{{property1}}' wird standardmassig verwendet.","invalidIndex":"{{elementType}}: '{{method}}' Die Methode akzeptiert einen Index der Typennummer oder ein Zahlenfeld.","indexOutOfBound":"{{elementType}}: ncht gebundener Index / Indizes in Methode '{{method}}'.","invalidItem":"{{elementType}}: '{{method}}' Die Methode akzeptiert ein Objekt oder ein Array von Objekten als zweiten Parameter.","invalidSettings":"{{elementType}}: '{{method}}' Die Methode akzeptiert einen string oder ein Objekt als zweiten Parameter."}}"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.messages = {"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."}};

Read the current value:

const el = document.querySelector('smart-list-box');
const messages = el.messages;

nameSets or retrieves the value of the element's name attribute. The name attribute identifies the element when submitting an HTML form, allowing its value to be included in the form data sent to the server. This is essential for processing form fields on the server-side.string

Sets or retrieves the value of the element's name attribute. The name attribute identifies the element when submitting an HTML form, allowing its value to be included in the form data sent to the server. This is essential for processing form fields on the server-side.

Default value

""""

Examples

Markup and runtime examples for name:

HTML:

<smart-list-box name="Name"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.name = "New Name";

Read the current value:

const el = document.querySelector('smart-list-box');
const name = el.name;

placeholderSpecifies the placeholder text that will be displayed in the List box when there are no available items to show. This text provides guidance or information to the user when the List box is empty.string

Specifies the placeholder text that will be displayed in the List box when there are no available items to show. This text provides guidance or information to the user when the List box is empty.

Default value

"No Items"

Examples

Markup and runtime examples for placeholder:

HTML:

<smart-list-box placeholder="Placeholder"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.placeholder = "New Placeholder";

Read the current value:

const el = document.querySelector('smart-list-box');
const placeholder = el.placeholder;

readonlySets or retrieves the readonly property of the element. When the readonly property is set to true, the element becomes non-editable—users can view its content but cannot modify it. This property is commonly used with input and textarea elements to prevent user interaction while still displaying the field’s value.boolean

Sets or retrieves the readonly property of the element. When the readonly property is set to true, the element becomes non-editable—users can view its content but cannot modify it. This property is commonly used with input and textarea elements to prevent user interaction while still displaying the field’s value.

Default value

false
Try a demo showcasing the readonly property.

Examples

Markup and runtime examples for readonly:

HTML attribute:

<smart-list-box readonly></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.readonly = true;

Read the current value:

const el = document.querySelector('smart-list-box');
const readonly = el.readonly;

rightToLeftSpecifies or retrieves a value that determines whether the element’s text direction is set to right-to-left (RTL) alignment, enabling proper display and support for languages and locales that use right-to-left scripts, such as Arabic or Hebrew.boolean

Specifies or retrieves a value that determines whether the element’s text direction is set to right-to-left (RTL) alignment, enabling proper display and support for languages and locales that use right-to-left scripts, such as Arabic or Hebrew.

Default value

false
Try a demo showcasing the rightToLeft property.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

<smart-list-box right-to-left></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.rightToLeft = true;

Read the current value:

const el = document.querySelector('smart-list-box');
const rightToLeft = el.rightToLeft;

selectAllControls whether the select all item is displayed when Checkboxes are enabled.boolean

Controls whether the select all item is displayed when Checkboxes are enabled.

Default value

false
Try a demo showcasing the selectAll property.

Examples

Markup and runtime examples for selectAll:

HTML attribute:

<smart-list-box select-all></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.selectAll = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const selectAll = el.selectAll;

selectedIndexesGets or sets the selected indexes. The selected indexes property is an array containing the numerical indexes of the items that are currently selected. Assigning an array of indexes will update the selection to match those items; retrieving this property returns the array of currently selected item indexes. number[]

Gets or sets the selected indexes. The selected indexes property is an array containing the numerical indexes of the items that are currently selected. Assigning an array of indexes will update the selection to match those items; retrieving this property returns the array of currently selected item indexes.

Try a demo showcasing the selectedIndexes property.

Examples

Markup and runtime examples for selectedIndexes:

HTML:

<smart-list-box selected-indexes="[1,2,3]"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.selectedIndexes = [4,5,6];

Read the current value:

const el = document.querySelector('smart-list-box');
const selectedIndexes = el.selectedIndexes;

selectedValuesSets or retrieves the selected indexes. The selected values correspond to the values of the items that are currently selected. When setting, provide an array of indexes or values to specify which items should be marked as selected; when getting, this returns the values associated with the selected items. string[]

Sets or retrieves the selected indexes. The selected values correspond to the values of the items that are currently selected. When setting, provide an array of indexes or values to specify which items should be marked as selected; when getting, this returns the values associated with the selected items.

Try a demo showcasing the selectedValues property.

Examples

Markup and runtime examples for selectedValues:

HTML:

<smart-list-box selected-values="["item 1"]"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.selectedValues = ["item 2"];

Read the current value:

const el = document.querySelector('smart-list-box');
const selectedValues = el.selectedValues;

selectionChangeActionSpecifies the user interaction event that triggers the selection of a listbox item: either when the item is initially pressed (‘press’) or when the user releases the press (‘release’). Choosing ‘press’ selects the item on mouse down or touch start, while ‘release’ selects it on mouse up or touch end. This setting controls how and when the user’s selection action is registered."press" | "release"

Specifies the user interaction event that triggers the selection of a listbox item: either when the item is initially pressed (‘press’) or when the user releases the press (‘release’). Choosing ‘press’ selects the item on mouse down or touch start, while ‘release’ selects it on mouse up or touch end. This setting controls how and when the user’s selection action is registered.

Default value

"release"
Try a demo showcasing the selectionChangeAction property.

Examples

Markup and runtime examples for selectionChangeAction:

HTML:

<smart-list-box selection-change-action="press"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.selectionChangeAction = "release";

Read the current value:

const el = document.querySelector('smart-list-box');
const selectionChangeAction = el.selectionChangeAction;

selectionModeSpecifies the maximum number of items that a user can select, based on the current selection mode (e.g., single, multiple, or none). This setting controls and restricts selection behavior within the interface."none" | "oneOrManyExtended" | "zeroOrMany" | "oneOrMany" | "zeroAndOne" | "zeroOrOne" | "one" | "checkBox" | "radioButton"

Specifies the maximum number of items that a user can select, based on the current selection mode (e.g., single, multiple, or none). This setting controls and restricts selection behavior within the interface.

Allowed Values

  • "none" - Item selection is not allowed.
  • "oneOrManyExtended" - Only one item can be selected but when pressing the Shift or Control keys of the keyboard more then one item can be selected. Shift key allows to select a range of items while Control allows to select/unselect speciic items. There is always at least one selected item
  • "zeroOrMany" - Zero or many items can be selected.
  • "oneOrMany" - One or more items must be selected. There is always at least one selected item
  • "zeroAndOne" - Only one item can optionally be selected.
  • "zeroOrOne" - Zero or one item can be selected.
  • "one" - Only one item can be selected. There is always at least one selected item
  • "checkBox" - A Check box appears next to every List item inside the List box. One, many or zero items can be selected.
  • "radioButton" - A radio button appears next to every List item inside the List box. Only one item can be selected or one item per group if grouped is enabled.

Default value

"oneOrManyExtended"
Try a demo showcasing the selectionMode property.

Examples

Markup and runtime examples for selectionMode:

HTML:

<smart-list-box selection-mode="zeroOrMany"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.selectionMode = "zeroOrOne";

Read the current value:

const el = document.querySelector('smart-list-box');
const selectionMode = el.selectionMode;

sortDirectionSpecifies the sorting order for the data. Accepts either 'asc' for ascending order (from lowest to highest) or 'desc' for descending order (from highest to lowest).string

Specifies the sorting order for the data. Accepts either 'asc' for ascending order (from lowest to highest) or 'desc' for descending order (from highest to lowest).

Default value

"asc"

Examples

Markup and runtime examples for sortDirection:

HTML:

<smart-list-box sort-direction="desc"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.sortDirection = "asc";

Read the current value:

const el = document.querySelector('smart-list-box');
const sortDirection = el.sortDirection;

sortedSpecifies whether the items should be automatically arranged in alphabetical order. If set to true, the items will be displayed from A to Z (or according to the selected locale’s alphabetical rules); if false, items will retain their original order.boolean

Specifies whether the items should be automatically arranged in alphabetical order. If set to true, the items will be displayed from A to Z (or according to the selected locale’s alphabetical rules); if false, items will retain their original order.

Default value

false
Try a demo showcasing the sorted property.

Examples

Markup and runtime examples for sorted:

HTML attribute:

<smart-list-box sorted></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.sorted = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const sorted = el.sorted;

themeSpecifies the visual theme applied to the element. Themes control the overall appearance, including colors, fonts, spacing, and other stylistic properties that define the element's look and feel. Choosing a theme ensures consistency and enhances the user interface design across the application.string

Specifies the visual theme applied to the element. Themes control the overall appearance, including colors, fonts, spacing, and other stylistic properties that define the element's look and feel. Choosing a theme ensures consistency and enhances the user interface design across the application.

Default value

""

Examples

Markup and runtime examples for theme:

HTML:

<smart-list-box theme="blue"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.theme = "red";

Read the current value:

const el = document.querySelector('smart-list-box');
const theme = el.theme;

topVisibleIndexScrolls the list box so that the item at the specified index appears as the first (topmost) visible item, ensuring it is fully in view at the top of the list.number

Scrolls the list box so that the item at the specified index appears as the first (topmost) visible item, ensuring it is fully in view at the top of the list.

Default value

-1

Examples

Markup and runtime examples for topVisibleIndex:

HTML:

<smart-list-box top-visible-index="20"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.topVisibleIndex = 2;

Read the current value:

const el = document.querySelector('smart-list-box');
const topVisibleIndex = el.topVisibleIndex;

unfocusableWhen set to true, this property prevents the element from receiving keyboard focus, meaning users will not be able to select the element using the keyboard (e.g., via the Tab key) or by programmatic focus methods.boolean

When set to true, this property prevents the element from receiving keyboard focus, meaning users will not be able to select the element using the keyboard (e.g., via the Tab key) or by programmatic focus methods.

Default value

false
Try a demo showcasing the unfocusable property.

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

<smart-list-box unfocusable></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.unfocusable = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const unfocusable = el.unfocusable;

unlockKeyGets or sets the unlockKey property, a unique code required to unlock access to the product. This key is used for product activation or to enable restricted features.string

Gets or sets the unlockKey property, a unique code required to unlock access to the product. This key is used for product activation or to enable restricted features.

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

<smart-list-box unlock-key=""></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.unlockKey = "1111-2222-3333-4444-5555";

Read the current value:

const el = document.querySelector('smart-list-box');
const unlockKey = el.unlockKey;

valueGets or sets the current selection value(s). This property returns an array of objects, where each object represents a selected option with the following structure: { label: string, value: any }. The 'label' is the display text shown to users, and 'value' holds the corresponding data for that option. Return type: { label: string, value: any }[].any

Gets or sets the current selection value(s). This property returns an array of objects, where each object represents a selected option with the following structure: { label: string, value: any }. The 'label' is the display text shown to users, and 'value' holds the corresponding data for that option. Return type: { label: string, value: any }[].

Try a demo showcasing the value property.

Examples

Markup and runtime examples for value:

HTML:

<smart-list-box value="1"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.value = 2;

Read the current value:

const el = document.querySelector('smart-list-box');
const value = el.value;

valueMemberDetermines which property of each item object should be used as the item's value. The specified property is stored as the value in the item object. Similar to groupMember, the valueMember property is particularly useful when binding data from a JSON file as a dataSource for the ListBox, allowing you to designate a specific field to serve as the value for each item. This is helpful when your data objects contain multiple properties, and you want to control exactly which one will represent the underlying value of each ListBox entry.string

Determines which property of each item object should be used as the item's value. The specified property is stored as the value in the item object. Similar to groupMember, the valueMember property is particularly useful when binding data from a JSON file as a dataSource for the ListBox, allowing you to designate a specific field to serve as the value for each item. This is helpful when your data objects contain multiple properties, and you want to control exactly which one will represent the underlying value of each ListBox entry.

Default value

""""
Try a demo showcasing the valueMember property.

Examples

Markup and runtime examples for valueMember:

HTML:

<smart-list-box value-member="value"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.valueMember = "newValue";

Read the current value:

const el = document.querySelector('smart-list-box');
const valueMember = el.valueMember;

verticalScrollBarVisibilityControls whether the vertical scroll bar is displayed, allowing users to scroll through content vertically when it overflows the container. This setting can be used to show, hide, or automatically display the scroll bar based on the content size."auto" | "disabled" | "hidden" | "visible"

Controls whether the vertical scroll bar is displayed, allowing users to scroll through content vertically when it overflows the container. This setting can be used to show, hide, or automatically display the scroll bar based on the content size.

Allowed Values

  • "auto" - The element automatically determines whether or not the horizontal Scroll bar should be visible or not.
  • "disabled" - Disables the horizontal Scroll bar.
  • "hidden" - Hides the horizontal Scroll bar.
  • "visible" - Shows the horizontal Scroll bar even if not necessary.

Default value

"auto"

Examples

Markup and runtime examples for verticalScrollBarVisibility:

HTML:

<smart-list-box vertical-scroll-bar-visibility="hidden"></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.verticalScrollBarVisibility = "visible";

Read the current value:

const el = document.querySelector('smart-list-box');
const verticalScrollBarVisibility = el.verticalScrollBarVisibility;

virtualizedSpecifies whether virtualization is enabled for the ListBox. When virtualization is enabled, the ListBox renders only the visible items in the UI, instead of generating UI elements for every item in the collection. This significantly improves performance and reduces memory usage, especially when working with large data sets (e.g., displaying one million items). Virtualization ensures smooth scrolling and responsiveness, even with a vast number of items in the ListBox.boolean

Specifies whether virtualization is enabled for the ListBox. When virtualization is enabled, the ListBox renders only the visible items in the UI, instead of generating UI elements for every item in the collection. This significantly improves performance and reduces memory usage, especially when working with large data sets (e.g., displaying one million items). Virtualization ensures smooth scrolling and responsiveness, even with a vast number of items in the ListBox.

Default value

false
Try a demo showcasing the virtualized property.

Examples

Markup and runtime examples for virtualized:

HTML attribute:

<smart-list-box virtualized></smart-list-box>

Vanilla JS — prefer #id if multiple widgets exist on the page:

const el = document.querySelector('smart-list-box');
el.virtualized = false;

Read the current value:

const el = document.querySelector('smart-list-box');
const virtualized = el.virtualized;

Events

bindingCompleteThis event is triggered after the listbox has successfully finished binding its data source. At this point, all data items have been loaded and rendered in the listbox, making it ready for user interaction or further programmatic manipulation. Use this event to perform actions that depend on the completion of data binding, such as customizing item appearance, enabling controls, or initiating additional data processing.CustomEvent

This event is triggered after the listbox has successfully finished binding its data source. At this point, all data items have been loaded and rendered in the listbox, making it ready for user interaction or further programmatic manipulation. Use this event to perform actions that depend on the completion of data binding, such as customizing item appearance, enabling controls, or initiating additional data processing.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onBindingComplete

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for bindingComplete using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('bindingComplete', (event) => {
	// event handling code goes here.
})

changeThis event is triggered whenever the user changes the current selection, such as when they select a different item from a list, dropdown, or any selectable element. It allows developers to respond dynamically to user input by detecting and handling selection changes in real time.CustomEvent

This event is triggered whenever the user changes the current selection, such as when they select a different item from a list, dropdown, or any selectable element. It allows developers to respond dynamically to user input by detecting and handling selection changes in real time.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onChange

Arguments

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

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the change event.

Examples

Listen for change using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('change', (event) => {
    const detail = event.detail,
        addedItems = detail.addedItems,
        disabled = detail.disabled,
        index = detail.index,
        label = detail.label,
        removedItems = detail.removedItems,
        selected = detail.selected,
        value = detail.value;

	// event handling code goes here.
})

dragEndThis event is fired when a user drops a draggable item onto a valid drop target. Within the event handler, you can call event.preventDefault() to cancel the default drop behavior, which allows you to define custom handling logic for the dropped item. This gives you full control over what should happen when an item is released on the target element.CustomEvent

This event is fired when a user drops a draggable item onto a valid drop target. Within the event handler, you can call event.preventDefault() to cancel the default drop behavior, which allows you to define custom handling logic for the dropped item. This gives you full control over what should happen when an item is released on the target element.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onDragEnd

Arguments

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

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for dragEnd using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('dragEnd', (event) => {
    const detail = event.detail,
        container = detail.container,
        data = detail.data,
        item = detail.item,
        originalEvent = detail.originalEvent,
        previousContainer = detail.previousContainer,
        target = detail.target;

	// event handling code goes here.
})

draggingThis event is triggered whenever a user starts dragging a list item, providing an opportunity to handle custom logic—such as updating the UI or managing the item's state—during the drag operation.CustomEvent

This event is triggered whenever a user starts dragging a list item, providing an opportunity to handle custom logic—such as updating the UI or managing the item's state—during the drag operation.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onDragging

Arguments

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

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for dragging using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('dragging', (event) => {
    const detail = event.detail,
        data = detail.data,
        item = detail.item,
        originalEvent = detail.originalEvent;

	// event handling code goes here.
})

dragStartThis event is triggered whenever a user initiates and performs a drag action on an item. Within the event handler, you can call event.preventDefault() to cancel or prevent the default drag behavior. This allows you to override the standard dragging operation and implement custom drag-and-drop functionality as needed.CustomEvent

This event is triggered whenever a user initiates and performs a drag action on an item. Within the event handler, you can call event.preventDefault() to cancel or prevent the default drag behavior. This allows you to override the standard dragging operation and implement custom drag-and-drop functionality as needed.

  • Bubbles Yes
  • Cancelable Yes
  • Interface CustomEvent
  • Event handler property onDragStart

Arguments

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

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the dragStart event.

Examples

Listen for dragStart using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('dragStart', (event) => {
    const detail = event.detail,
        container = detail.container,
        data = detail.data,
        item = detail.item,
        originalEvent = detail.originalEvent,
        previousContainer = detail.previousContainer,
        target = detail.target;

	// event handling code goes here.
})

itemClickThis event is triggered whenever a user clicks on an item within the component. It provides detailed information about the clicked item, such as its identifier and relevant data, enabling you to implement custom logic in response to user interactions.CustomEvent

This event is triggered whenever a user clicks on an item within the component. It provides detailed information about the clicked item, such as its identifier and relevant data, enabling you to implement custom logic in response to user interactions.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onItemClick

Arguments

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

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for itemClick using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('itemClick', (event) => {
    const detail = event.detail,
        disabled = detail.disabled,
        index = detail.index,
        label = detail.label,
        selected = detail.selected,
        value = detail.value;

	// event handling code goes here.
})

itemLabelChangeThis event is triggered immediately after an item has been modified and the changes have been saved. It allows you to respond to updates or modifications made to an item's data.CustomEvent

This event is triggered immediately after an item has been modified and the changes have been saved. It allows you to respond to updates or modifications made to an item's data.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onItemLabelChange

Arguments

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

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for itemLabelChange using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('itemLabelChange', (event) => {
    const detail = event.detail,
        selected = detail.selected,
        disabled = detail.disabled,
        index = detail.index,
        label = detail.label,
        value = detail.value;

	// event handling code goes here.
})

scrollBottomReachedThis event is triggered when the user scrolls to the bottom of the list, indicating that the end of the available items has been reached. It can be used to load additional data or perform actions when no more items are visible in the current list view.CustomEvent

This event is triggered when the user scrolls to the bottom of the list, indicating that the end of the available items has been reached. It can be used to load additional data or perform actions when no more items are visible in the current list view.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onScrollBottomReached

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for scrollBottomReached using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('scrollBottomReached', (event) => {
	// event handling code goes here.
})

scrollTopReachedThis event is triggered when the user scrolls to the very top of the list, indicating that the first item in the list is visible or has been reached. It can be used to implement features such as loading previous items, displaying a refresh indicator, or updating the UI when the user navigates to the start of the list.CustomEvent

This event is triggered when the user scrolls to the very top of the list, indicating that the first item in the list is visible or has been reached. It can be used to implement features such as loading previous items, displaying a refresh indicator, or updating the UI when the user navigates to the start of the list.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onScrollTopReached

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Examples

Listen for scrollTopReached using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('scrollTopReached', (event) => {
	// event handling code goes here.
})

swipeleftThis event is triggered when the user performs a leftward swipe gesture within the boundaries of the listBox component. It can be used to initiate actions such as revealing additional options, deleting a list item, or any other behavior that should occur in response to a left swipe inside the listBox.CustomEvent

This event is triggered when the user performs a leftward swipe gesture within the boundaries of the listBox component. It can be used to initiate actions such as revealing additional options, deleting a list item, or any other behavior that should occur in response to a left swipe inside the listBox.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onSwipeleft

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the swipeleft event.

Examples

Listen for swipeleft using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('swipeleft', (event) => {
	// event handling code goes here.
})

swiperightThis event is triggered when the user performs a rightward swipe gesture within the boundaries of the listBox component. It detects intentional swipe actions to the right, allowing developers to respond to user navigation or interaction within the listBox. The event will only fire if the swipe is initiated and completed inside the listBox area.CustomEvent

This event is triggered when the user performs a rightward swipe gesture within the boundaries of the listBox component. It detects intentional swipe actions to the right, allowing developers to respond to user navigation or interaction within the listBox. The event will only fire if the swipe is initiated and completed inside the listBox area.

  • Bubbles Yes
  • Cancelable No
  • Interface CustomEvent
  • Event handler property onSwiperight

Arguments

evCustomEvent

Methods

isDefaultPrevented

Returns true if the event was prevented by any of its subscribers.

Returns

boolean true if the default action was prevented. Otherwise, returns false.

preventDefault

The preventDefault() method prevents the default action for a specified event. In this way, the source component suppresses the built-in behavior that follows the event.

stopPropagation

The stopPropagation() method of the Event interface prevents further propagation of the current event in the capturing and bubbling phases.

Try a demo showcasing the swiperight event.

Examples

Listen for swiperight using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-list-box')?.addEventListener('swiperight', (event) => {
	// event handling code goes here.
})

Methods

add( item: any): voidAdds one or more new items to the collection. This operation updates the data set by appending the provided item(s), making them available for future retrieval or processing.

Adds one or more new items to the collection. This operation updates the data set by appending the provided item(s), making them available for future retrieval or processing.

Arguments

itemany

Describes the properties of the item that will be inserted. You can also pass an array of items.

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

document.querySelector('smart-list-box')?.add("'New item'");

Try a demo showcasing the add method.

appendChild( node: Node): TAdds a new ListItem element to the end of the existing items within the specified container element, maintaining the original order of all previously added items.

Arguments

nodeNode

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

ReturnsNode

clearItems(): voidClears all items from the listBox, effectively removing every entry and leaving the listBox empty. This operation does not delete the listBox itself, only its contents.

Clears all items from the listBox, effectively removing every entry and leaving the listBox empty. This operation does not delete the listBox itself, only its contents.

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

document.querySelector('smart-list-box')?.clearItems();

Try a demo showcasing the clearItems method.

clearSelection(): voidDeselects all currently selected items, ensuring that no items remain selected within the list or interface.

Deselects all currently selected items, ensuring that no items remain selected within the list or interface.

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

document.querySelector('smart-list-box')?.clearSelection();

Try a demo showcasing the clearSelection method.

dataBind(): voidBinds the latest data from the data source to the component, ensuring the user interface reflects current information. This method can be called to refresh or update the displayed data whenever the data source changes.

Binds the latest data from the data source to the component, ensuring the user interface reflects current information. This method can be called to refresh or update the displayed data whenever the data source changes.

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

document.querySelector('smart-list-box')?.dataBind();

Try a demo showcasing the dataBind method.

ensureVisible( item: HTMLElement | string): voidScrolls the container so that the target item is brought into view, ensuring it is fully visible to the user within the viewport or scrollable area.

Scrolls the container so that the target item is brought into view, ensuring it is fully visible to the user within the viewport or scrollable area.

Arguments

itemHTMLElement | string

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

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

document.querySelector('smart-list-box')?.ensureVisible("'item1'");

getItem( value: string): HTMLElementReturns a specific item instance from the listBox based on the provided index or selection criteria. The returned object represents the selected item and includes its associated properties and methods for further manipulation.

Returns a specific item instance from the listBox based on the provided index or selection criteria. The returned object represents the selected item and includes its associated properties and methods for further manipulation.

Arguments

valuestring

The value of an item from the listBox.

ReturnsHTMLElement

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

const result = document.querySelector('smart-list-box')?.getItem("First");

Try a demo showcasing the getItem method.

getItems(): {label: string, value: string}[]Returns an array containing all items currently present in the ListBox component. Each item in the array represents an individual entry within the ListBox, typically as an object with relevant properties such as value, label, and any other associated data. This allows developers to access, display, or manipulate the full set of ListBox options programmatically.

Returns an array containing all items currently present in the ListBox component. Each item in the array represents an individual entry within the ListBox, typically as an object with relevant properties such as value, label, and any other associated data. This allows developers to access, display, or manipulate the full set of ListBox options programmatically.

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

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

const result = document.querySelector('smart-list-box')?.getItems();

getSelectedValues(): []Returns an array of the selected values.

Returns an array of the selected values.

Returns[]

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

const result = document.querySelector('smart-list-box')?.getSelectedValues();

Try a demo showcasing the getSelectedValues method.

insert( index: number, items: any): voidInserts a new item into the collection at the specified index, shifting existing items at and after that position one place to the right. The index determines the position in the array or list where the new item will be placed.

Inserts a new item into the collection at the specified index, shifting existing items at and after that position one place to the right. The index determines the position in the array or list where the new item will be placed.

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.

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

document.querySelector('smart-list-box')?.insert(5,"'New item'");

Try a demo showcasing the insert method.

insertBefore( node: Node, referenceNode: Node | null): TInserts a new ListItem element into the list, placing it immediately before a specified existing ListItem. This ensures the new item appears in the correct sequence relative to the given reference item.

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): voidRemoves the item located at the specified index from the collection or array. The operation shifts all subsequent items one position to the left, effectively reducing the total number of items by one. The specified index must be within the valid range; otherwise, an error may occur.

Removes the item located at the specified index from the collection or array. The operation shifts all subsequent items one position to the left, effectively reducing the total number of items by one. The specified index must be within the valid range; otherwise, an error may occur.

Arguments

indexnumber

The index of the removed item.

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

document.querySelector('smart-list-box')?.removeAt(5);

Try a demo showcasing the removeAt method.

removeChild( node: Node): TRemoves a specific ListItem from the collection of items contained within the given element. This operation updates the element by deleting the specified ListItem from its current list of child items.

Arguments

nodeNode

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

ReturnsNode

select( item: string | number | HTMLElement): voidSelects a specific item from the ListBox component by programmatically highlighting or activating it, allowing for interaction as if the user had manually chosen the item from the list.

Selects a specific item from the ListBox component by programmatically highlighting or activating it, allowing for interaction as if the user had manually chosen the item from the list.

Arguments

itemstring | number | HTMLElement

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

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

document.querySelector('smart-list-box')?.select("'First Item'");

Try a demo showcasing the select method.

unselect( item: string | HTMLElement): voidRemoves the selection from a specified item in the listBox component, ensuring that the item is no longer highlighted or considered selected by the application.

Removes the selection from a specified item in the listBox component, ensuring that the item is no longer highlighted or considered selected by the application.

Arguments

itemstring | HTMLElement

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

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

document.querySelector('smart-list-box')?.unselect("'First Item'");

Try a demo showcasing the unselect method.

update( index: number, details: any): voidUpdates the properties or content of a specific item within the listBox control. This operation identifies the targeted item based on its index or unique identifier and applies the specified changes, ensuring the listBox reflects the latest data or state.

Updates the properties or content of a specific item within the listBox control. This operation identifies the targeted item based on its index or unique identifier and applies the specified changes, ensuring the listBox reflects the latest data or state.

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.

On the custom element in the DOM (narrow the selector, e.g. to #my-listbox, if you host multiple widgets):

document.querySelector('smart-list-box')?.update(5,"'Updated item'");

Try a demo showcasing the update method.

CSS Variables

--smart-list-box-default-widthvar()

Default value

"var(--smart-editor-width)"

smartListBox default width

--smart-list-box-default-heightvar()

Default value

"var(--smart-editor-width)"

smartListBox default height

--smart-list-item-group-header-text-transformvar()

Default value

"uppercase"

smartListBox item group header text transform

--smart-list-item-horizontal-offsetvar()

Default value

"3px"

Defines list item's horizontal offset.

--smart-list-item-vertical-offsetvar()

Default value

"3px"

Defines list item's vertical offset.

--smart-list-item-heightvar()

Default value

"36px"

smartListBox item height

--smart-list-item-check-box-radiusvar()

Default value

"2px"

smartListBox checkbox radius

--smart-list-item-label-paddingvar()

Default value

"0"

smartListBox item label padding

--smart-list-item-label-border-radiusvar()

Default value

"0"

smartListBox item label border radius

ListItem

Defines a list item for ListBox, ComboBox, DropDownList.

Selector

smart-list-item

Quick picks

value

Properties

AalternationIndexalternationIndex
Ccolorcolor
Ddetailsdetails
DdisplayModedisplayMode
Ggroupgroup
Ggroupedgrouped
Hhiddenhidden
Llabellabel
Rreadonlyreadonly
Sselectedselected
Vvaluevalue

Properties

alternationIndexnumber

Default value

-1

colorstring

Default value

""

detailsstring

Default value

""

displayMode"plain" | "checkBox" | "radioButton"

Default value

"plain"

groupstring

Default value

""

groupedboolean

Default value

false

HTML attribute:

<smart-list-item grouped></smart-list-item>

hiddenboolean

Default value

false

HTML attribute:

<smart-list-item hidden></smart-list-item>

labelstring

Default value

""

readonlyboolean

Default value

false

HTML attribute:

<smart-list-item readonly></smart-list-item>

selectedboolean

Default value

false

HTML attribute:

<smart-list-item selected></smart-list-item>

valuestring

Default value

""

ListItemsGroup

Defines a group of list items.

Selector

smart-list-items-group

Properties

Llabellabel

Properties

labelstring

Default value

""