DropDownList JAVASCRIPT UI Component API

DropDownList Javascript API

DropDownList

The DropDownList is a form component that lets you choose a single predefined value from a list. It is a more advanced version of the 'select' tag.

This property applies exclusively when dropDownOpenMode is set to 'auto'. It specifies the amount of time (in milliseconds) to wait before automatically closing the open drop-down if the user's pointer (mouse or touch) is no longer hovering over the drop-down element. A higher value increases the delay before closing, while a lower value causes the drop-down to close more quickly when the pointer leaves.

Default value

100

Example

Set the autoCloseDelay property.

 <smart-drop-down-list auto-close-delay='50'></smart-drop-down-list>

Set the autoCloseDelay property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.autoCloseDelay = 200;

Get the autoCloseDelay property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let autoCloseDelay = dropdownlist.autoCloseDelay;

dataSourceany

Specifies the source of data that populates the DropDownList. The 'dataSource' property accepts:

- An array of strings or numbers (e.g., '['Option 1', 'Option 2']'), where each element becomes a list item.
- An array of objects, where each object defines the properties of a list item. Common object attributes include:
- label: The text displayed for the list item.
- value: The underlying value associated with the list item.
- group (optional): Used to group items under a common category.
- A callback function that returns an array in either of the above formats.

This flexibility allows you to easily provide simple lists or complex, structured data for display in the DropDownList.

Example

Set the dataSource property.

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

Set the dataSource property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dataSource = ["new item 1", "new item 2"];

Get the dataSource property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dataSource = dropdownlist.dataSource;

disabledboolean

Determines whether the element is interactive or inactive. When enabled, users can interact with the element; when disabled, the element is non-interactive and may appear visually distinct (e.g., grayed out).

Default value

false

Try a demo showcasing the disabled property.

Example

Set the disabled property.

 <smart-drop-down-list disabled></smart-drop-down-list>

Set the disabled property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.disabled = false;

Get the disabled property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let disabled = dropdownlist.disabled;

displayLoadingIndicatorboolean

Specifies whether a visual indicator (such as a loading spinner or progress bar) is displayed while filtering data or loading items from a remote source. This helps inform users that a background operation is in progress.

Default value

false

Example

Set the displayLoadingIndicator property.

 <smart-drop-down-list display-loading-indicator></smart-drop-down-list>

Set the displayLoadingIndicator property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.displayLoadingIndicator = false;

Get the displayLoadingIndicator property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let displayLoadingIndicator = dropdownlist.displayLoadingIndicator;

displayMemberstring

Sets or retrieves the displayMember property. The displayMember defines which property of the objects within the collection (specified by the dataSource property) should be shown in the UI. When binding a data source containing objects, displayMember indicates the key whose corresponding value will be rendered for each item in the component's display.

Default value

""""

Example

Set the displayMember property.

 <smart-drop-down-list display-member='label'></smart-drop-down-list>

Set the displayMember property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.displayMember = 'name';

Get the displayMember property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let displayMember = dropdownlist.displayMember;

dropDownAppendTostring

''

Specifies the parent container for the dropdown menu. The value can be a CSS selector, an element ID, the string ''body'', or a direct reference to an HTML element. By default, the dropdown is rendered within its original parent. However, if a parent element restricts overflow (e.g., 'overflow: hidden'), setting this property to ''body'' or another container allows the dropdown to be rendered elsewhere in the DOM. This ensures that the dropdown remains visible and fully functional even when its original parent would otherwise clip or hide it.

The dropDownAppendTo property accepts:
- A string representing a CSS selector or element ID (e.g., ''#container'' or ''.custom-dropdown-wrapper''),
- The string ''body'' to append directly to the document body,
- Or a direct reference to an HTML element.

To revert the dropdown to its original parent container, set dropDownAppendTo to 'null'. This flexibility helps accommodate layouts where dropdown overflow is restricted by ancestor elements.

'Example Usage:'
'''json
{
"dropDownAppendTo": "body"
}
'''
or
'''json
{
"dropDownAppendTo": "#customContainer"
}
'''
or
'''json
{
"dropDownAppendTo": null
}
'''

Default value

"null"

Try a demo showcasing the dropDownAppendTo property.

Example

Set the dropDownAppendTo property.

 <smart-drop-down-list drop-down-append-to=''body''></smart-drop-down-list>

Set the dropDownAppendTo property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownAppendTo = 'null';

Get the dropDownAppendTo property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownAppendTo = dropdownlist.dropDownAppendTo;

dropDownButtonPosition"left" | "right" | "top" | "bottom"

Specifies the alignment or placement of the dropdown button relative to its container or associated input field. This setting controls where the dropdown button appears—such as to the left, right, top, or bottom—within the user interface component.

Allowed Values

"left" - Positions the drop down button on the left side of the element.
"right" - Positions the drop down button on the right side of the element.
"top" - Positions the drop down button on the top side of the element.
"bottom" - Positions the drop down button on the bottom side of the element.

Default value

"right"

Try a demo showcasing the dropDownButtonPosition property.

Example

Set the dropDownButtonPosition property.

 <smart-drop-down-list drop-down-button-position='top'></smart-drop-down-list>

Set the dropDownButtonPosition property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownButtonPosition = 'bottom';

Get the dropDownButtonPosition property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownButtonPosition = dropdownlist.dropDownButtonPosition;

dropDownHeightstring | number

Specifies the height of the dropdown component. By default, this property is set to an empty string, which means the dropdown's height will be determined by a corresponding CSS variable. If a specific value is provided (e.g., "200px" or "50%"), it directly sets the dropdown's height, overriding the CSS variable.

Default value

Example

Set the dropDownHeight property.

 <smart-drop-down-list drop-down-height='300'></smart-drop-down-list>

Set the dropDownHeight property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownHeight = 500;

Get the dropDownHeight property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownHeight = dropdownlist.dropDownHeight;

dropDownMaxHeightstring | number

Defines the maximum height of the dropdown component. By default, this property is set to an empty string, meaning the dropdown’s maximum height will be determined by the associated CSS variable rather than a fixed value. Setting a specific value (such as '"200px"' or '"50vh"') will override the CSS variable and directly control the dropdown's maximum height. If left as an empty string, ensure that the relevant CSS variable is defined to maintain consistent dropdown sizing.

Default value

Example

Set the dropDownMaxHeight property.

 <smart-drop-down-list drop-down-max-height='800'></smart-drop-down-list>

Set the dropDownMaxHeight property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownMaxHeight = 1000;

Get the dropDownMaxHeight property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownMaxHeight = dropdownlist.dropDownMaxHeight;

dropDownMaxWidthstring | number

Specifies the maximum width of the dropdown menu. By default, this property is set to an empty string, meaning the dropdown's maximum width will be determined by a corresponding CSS variable (typically via a style such as --dropdown-max-width). To override the CSS variable and set a specific maximum width, provide a valid CSS width value (e.g., "300px" or "50%") for this property.

Default value

Example

Set the dropDownMaxWidth property.

 <smart-drop-down-list drop-down-max-width='500'></smart-drop-down-list>

Set the dropDownMaxWidth property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownMaxWidth = 800;

Get the dropDownMaxWidth property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownMaxWidth = dropdownlist.dropDownMaxWidth;

dropDownMinHeightstring | number

Specifies the minimum height for the dropdown menu. By default, this property is set to an empty string (""). When left empty, the dropdown's minimum height is determined by a corresponding CSS variable, allowing you to control the minimum height through your stylesheet. If a specific value is provided (such as '200px' or '3rem'), it directly sets the minimum height of the dropdown, overriding the CSS variable.

Default value

Example

Set the dropDownMinHeight property.

 <smart-drop-down-list drop-down-min-height='50'></smart-drop-down-list>

Set the dropDownMinHeight property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownMinHeight = 150;

Get the dropDownMinHeight property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownMinHeight = dropdownlist.dropDownMinHeight;

dropDownMinWidthstring | number

Specifies the minimum width of the dropdown menu. By default, this value is an empty string, which means the dropdown’s minimum width is determined by a CSS variable rather than a fixed value. If a specific width is provided, it overrides the CSS variable, setting the dropdown’s minimum width to the specified value.

Default value

Example

Set the dropDownMinWidth property.

 <smart-drop-down-list drop-down-min-width='100'></smart-drop-down-list>

Set the dropDownMinWidth property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownMinWidth = 90;

Get the dropDownMinWidth property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownMinWidth = dropdownlist.dropDownMinWidth;

dropDownOpenMode"none" | "default" | "dropDownButton" | "auto"

Specifies the direction or animation style in which the dropdown menu will appear when activated, such as opening upwards, downwards, to the left, to the right, or with a specific transition effect.

Allowed Values

"none" - The drop down can't be opened.
"default" - The drop down opens when the user clicks on the element
"dropDownButton" - The element is split in two button: action and drop down buttons. The drop down opens only when the button is clicked. The action button fires a custom event when clicked on. The event can be used to execute a custom operation on click.
"auto" - The drop down opens when the element is hovered and closed when not.

Default value

"default"

Try a demo showcasing the dropDownOpenMode property.

Example

Set the dropDownOpenMode property.

 <smart-drop-down-list drop-down-open-mode='dropDownButton'></smart-drop-down-list>

Set the dropDownOpenMode property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownOpenMode = 'auto';

Get the dropDownOpenMode property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownOpenMode = dropdownlist.dropDownOpenMode;

dropDownOverlayboolean

If this property is enabled, opening the element’s dropdown will display a transparent overlay that covers the area between the dropdown and the rest of the document. The overlay ensures that any clicks outside of the dropdown are captured by the overlay itself, rather than interacting with other DOM elements on the page. This behavior allows the dropdown to be closed when users click outside of it, and prevents unintended interactions with background content while the dropdown is open.

Default value

false

Example

Set the dropDownOverlay property.

 <smart-drop-down-list drop-down-overlay></smart-drop-down-list>

Set the dropDownOverlay property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownOverlay = false;

Get the dropDownOverlay property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownOverlay = dropdownlist.dropDownOverlay;

dropDownPlaceholderstring

Specifies the text displayed in the dropdown list when no option is currently selected, serving as a placeholder to guide the user.

Default value

"No Items"

Example

Set the dropDownPlaceholder property.

 <smart-drop-down-list drop-down-placeholder='Empty'></smart-drop-down-list>

Set the dropDownPlaceholder property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownPlaceholder = 'Empty drop down';

Get the dropDownPlaceholder property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownPlaceholder = dropdownlist.dropDownPlaceholder;

dropDownPosition"auto" | "top" | "bottom" | "overlay-top" | "overlay-center" | "overlay-bottom" | "center-bottom" | "center-top"

Specifies the placement of the dropdown menu relative to its trigger element when opened, such as above, below, to the left, or to the right. This setting ensures the dropdown appears in the desired location on the screen when activated.

Allowed Values

"auto" - The position is automatically determined by measuring the available distance around the element for the drop down to open freely without being clipped by the edges of the browser. By default the drop down will try to open below the element. If the available space is not enough for the popup to appear it will open in one of the following directions, if possible: top, over.
"top" - The drop down opens above the element.
"bottom" - The drop down opens under the element.
"overlay-top" - The drop down opens above and over the element. The bottom edges of the drop down cover the element.
"overlay-center" - The drop down opens at the center, over the element.
"overlay-bottom" - The drop down opens under and over the element. The top edges of the drop down cover the element.
"center-bottom" - The drop down opens at the center, below the element.
"center-top" - The drop down opens at the center, over the element.

Default value

"auto"

Try a demo showcasing the dropDownPosition property.

Example

Set the dropDownPosition property.

 <smart-drop-down-list drop-down-position='top'></smart-drop-down-list>

Set the dropDownPosition property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownPosition = 'bottom';

Get the dropDownPosition property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownPosition = dropdownlist.dropDownPosition;

dropDownWidthstring | number

Specifies the width of the dropdown component. By default, this property is set to an empty string (""). When left empty, the dropdown’s width is determined by a corresponding CSS variable, allowing for flexible styling through external stylesheets. You can override this by providing a specific width value (e.g., "200px" or "50%"), which will directly set the dropdown’s width in the component’s inline styles.

Default value

Example

Set the dropDownWidth property.

 <smart-drop-down-list drop-down-width='300'></smart-drop-down-list>

Set the dropDownWidth property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.dropDownWidth = 500;

Get the dropDownWidth property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let dropDownWidth = dropdownlist.dropDownWidth;

filterableboolean

Specifies whether the filtering feature is active, allowing users to narrow down or refine the displayed data based on specific criteria. Set this option to true to enable filtering, or false to disable it.

Default value

false

Try a demo showcasing the filterable property.

Example

Set the filterable property.

 <smart-drop-down-list filterable></smart-drop-down-list>

Set the filterable property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.filterable = false;

Get the filterable property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let filterable = dropdownlist.filterable;

filterInputPlaceholderstring

Specifies the placeholder text displayed within the filter input field inside the dropdown. This input field is visible only when the filterable option is enabled, providing users with a prompt or hint about the expected input for filtering dropdown options.

Default value

Example

Set the filterInputPlaceholder property.

 <smart-drop-down-list filter-input-placeholder='Enter a value:'></smart-drop-down-list>

Set the filterInputPlaceholder property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.filterInputPlaceholder = 'Awaiting entry:';

Get the filterInputPlaceholder property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let filterInputPlaceholder = dropdownlist.filterInputPlaceholder;

filterMode"contains" | "containsIgnoreCase" | "custom" | "doesNotContain" | "doesNotContainIgnoreCase" | "equals" | "equalsIgnoreCase" | "startsWith" | "startsWithIgnoreCase" | "endsWith" | "endsWithIgnoreCase"

Specifies the filtering behavior applied to the dropdown list, such as how user input is used to match and display available options. This setting controls whether the dropdown filters items by starting characters, contains matching text, or applies a custom filtering strategy.

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)
"custom" - filtering is applied according to the callback function filterCallback
"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)

Default value

"startsWithIgnoreCase"

Example

Set the filterMode property.

 <smart-drop-down-list filter-mode='contains'></smart-drop-down-list>

Set the filterMode property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.filterMode = 'equals';

Get the filterMode property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let filterMode = dropdownlist.filterMode;

filterCallbackfunction | null

A callback function that must return a filtering condition (typically a boolean or a predicate function) to determine whether each item should be included or excluded from the results. This is specifically used when filterMode is set to 'custom', allowing you to implement your own custom filtering logic for items.

Try a demo showcasing the filterCallback property.

Example

Set the filterCallback property.

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

Set the filterCallback property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.filterCallback = function(item, searchQuery) { return item.value > 5 };

Get the filterCallback property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let filterCallback = dropdownlist.filterCallback;

groupedboolean

When enabled, this option will automatically group the items by the first letter of each item's value. Note: This setting cannot be used if the dataSource already includes predefined groups, as grouping by first letter is only applicable to flat, ungrouped data.

Default value

false

Try a demo showcasing the grouped property.

Example

Set the grouped property.

 <smart-drop-down-list grouped></smart-drop-down-list>

Set the grouped property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.grouped = false;

Get the grouped property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let grouped = dropdownlist.grouped;

groupMemberstring | null

Specifies which property of each object in the dataSource should be used to group items in the ListBox. By default, the ListBox looks for a property named group in each data object to determine grouping. Setting the groupMember attribute allows you to define a custom property name to use for grouping instead. This is particularly useful when your data is loaded from a JSON file and the grouping property has a name other than "group".

Example

Set the groupMember property.

 <smart-drop-down-list group-member='group'></smart-drop-down-list>

Set the groupMember property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.groupMember = section;

Get the groupMember property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let groupMember = dropdownlist.groupMember;

hintstring

Specifies supplementary helper text that appears below the element. This hint is displayed exclusively when the element is in focus, providing contextual guidance to the user as they interact with the field.

Default value

Example

Set the hint property.

 <smart-drop-down-list hint='Helper text'></smart-drop-down-list>

Set the hint property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.hint = 'Hint';

Get the hint property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let hint = dropdownlist.hint;

horizontalScrollBarVisibility"auto" | "disabled" | "hidden" | "visible"

Controls whether a horizontal scroll bar is displayed within the dropdown menu. Enabling this option allows users to scroll horizontally to view content that extends beyond the visible width of the dropdown.

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"

Example

Set the horizontalScrollBarVisibility property.

 <smart-drop-down-list horizontal-scroll-bar-visibility='disabled'></smart-drop-down-list>

Set the horizontalScrollBarVisibility property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.horizontalScrollBarVisibility = 'hidden';

Get the horizontalScrollBarVisibility property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let horizontalScrollBarVisibility = dropdownlist.horizontalScrollBarVisibility;

inputMemberstring

Represents the specific property name of an item within a List that should be displayed in the input field when a ListItem is selected. This allows developers to control which attribute of the List data appears in the input—such as displaying an item's value (e.g., an ID or code) instead of its label or name. This property is useful when you want to show a value other than the default label in the input element. By default, the input will display the item's label unless a different property name is specified.

Default value

Example

Set the inputMember property.

 <smart-drop-down-list input-member='label'></smart-drop-down-list>

Set the inputMember property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.inputMember = 'value';

Get the inputMember property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let inputMember = dropdownlist.inputMember;

incrementalSearchDelaynumber

The 'IncrementalSearchDelay' property defines the time interval, in milliseconds, that must elapse after the user stops typing before the previous search query is automatically cleared. This delay timer begins counting once the user has stopped input, preventing the search from triggering immediately with each keystroke. Only after the specified delay has passed can a new search query be initiated, ensuring that searches are not executed too frequently and improving performance for incremental search operations.

Default value

700

Example

Set the incrementalSearchDelay property.

 <smart-drop-down-list incremental-search-delay='100'></smart-drop-down-list>

Set the incrementalSearchDelay property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.incrementalSearchDelay = 500;

Get the incrementalSearchDelay property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let incrementalSearchDelay = dropdownlist.incrementalSearchDelay;

incrementalSearchMode"contains" | "containsIgnoreCase" | "doesNotContain" | "doesNotContainIgnoreCase" | "equals" | "equalsIgnoreCase" | "startsWith" | "startsWithIgnoreCase" | "endsWith" | "endsWithIgnoreCase"

Gets or sets the incremental search mode for the dropdown. When incremental search is enabled (the default setting), typing while the dropdown is focused will automatically search and highlight matching items based on the input characters. This property allows you to enable or disable this behavior as needed.

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"

Example

Set the incrementalSearchMode property.

 <smart-drop-down-list incremental-search-mode='contains'></smart-drop-down-list>

Set the incrementalSearchMode property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.incrementalSearchMode = 'endsWith';

Get the incrementalSearchMode property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let incrementalSearchMode = dropdownlist.incrementalSearchMode;

itemHeightnumber | null

Specifies the height (in pixels) for each list item when rendering the component. This property takes effect only when virtualization is enabled, ensuring consistent and accurate item measurements for optimized scrolling performance.

Example

Set the itemHeight property.

 <smart-drop-down-list item-height='20'></smart-drop-down-list>

Set the itemHeight property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.itemHeight = 50;

Get the itemHeight property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let itemHeight = dropdownlist.itemHeight;

itemMeasureMode"auto" | "precise"

Specifies the algorithm used to calculate the width of each item, affecting how items are sized and displayed within the layout. Select the desired measurement method to control item width behavior.

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"

Example

Set the itemMeasureMode property.

 <smart-drop-down-list item-measure-mode='precise'></smart-drop-down-list>

Set the itemMeasureMode property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.itemMeasureMode = 'auto';

Get the itemMeasureMode property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let itemMeasureMode = dropdownlist.itemMeasureMode;

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

A getter that retrieves and returns an array containing all list item elements ('

') currently present within the dropdown menu. This allows easy access to each item for further processing or manipulation.

Default value

itemTemplateany

The 'itemTemplate' property accepts either a string representing the 'id' of an 'HTMLTemplateElement' present in the DOM, or a direct reference to an 'HTMLTemplateElement' object. This template is used to define and customize the layout and content of each item rendered within the list. By specifying an 'itemTemplate', developers can control exactly how each list item appears, enabling advanced customization beyond default rendering.

Try a demo showcasing the itemTemplate property.

Example

Set the itemTemplate property.

 <smart-drop-down-list item-template=''templateA''></smart-drop-down-list>

Set the itemTemplate property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.itemTemplate = 'templateB';

Get the itemTemplate property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let itemTemplate = dropdownlist.itemTemplate;

labelstring

Displays a small text label positioned above the element, typically used to provide additional information or context, such as a tooltip, caption, or section heading.

Default value

Example

Set the label property.

 <smart-drop-down-list label='Helper text'></smart-drop-down-list>

Set the label property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.label = 'Label';

Get the label property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let label = dropdownlist.label;

loadingIndicatorPlaceholderstring

Specifies the text label that appears alongside the loading indicator when it is visible and positioned at either the top or bottom of the component. This text provides additional context or messaging to users during loading states.

Default value

"Loading..."

Example

Set the loadingIndicatorPlaceholder property.

 <smart-drop-down-list loading-indicator-placeholder='Incoming data'></smart-drop-down-list>

Set the loadingIndicatorPlaceholder property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.loadingIndicatorPlaceholder = 'LOADING...';

Get the loadingIndicatorPlaceholder property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let loadingIndicatorPlaceholder = dropdownlist.loadingIndicatorPlaceholder;

loadingIndicatorPosition"bottom" | "center" | "top"

Specifies the exact location on the user interface where the loading indicator will appear (e.g., top, center, bottom, or custom coordinates), allowing you to control its placement during loading operations.

Allowed Values

"bottom" - Positions the loading indicator at the bottom of the list.
"center" - Positions the loading indicator at the center of the list.
"top" - Positions the loading indicator at the bottom of the list.

Default value

"center"

Example

Set the loadingIndicatorPosition property.

 <smart-drop-down-list loading-indicator-position='bottom'></smart-drop-down-list>

Set the loadingIndicatorPosition property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.loadingIndicatorPosition = 'top';

Get the loadingIndicatorPosition property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let loadingIndicatorPosition = dropdownlist.loadingIndicatorPosition;

unlockKeystring

Defines or retrieves the 'unlockKey' property. The 'unlockKey' is a unique identifier or code required to unlock access to the product’s features or content. Setting this property assigns the key needed for authentication or activation, while getting it retrieves the currently assigned unlock key.

Default value

Example

Set the unlockKey property.

 <smart-drop-down-list unlock-key=''></smart-drop-down-list>

Set the unlockKey property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.unlockKey = '1111-2222-3333-4444-5555';

Get the unlockKey property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let unlockKey = dropdownlist.unlockKey;

localestring

Sets or retrieves the current language code (e.g., 'en', 'es', 'fr') used by the application or component. This property works together with the messages property, allowing you to display localized content based on the selected language. When you change the language, the corresponding localized messages from the messages object will be used throughout the interface.

Default value

"en"

Example

Set the locale property.

 <smart-drop-down-list locale='de'></smart-drop-down-list>

Set the locale property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.locale = 'en';

Get the locale property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let locale = dropdownlist.locale;

localizeFormatFunctionfunction | null

Callback function that allows you to define a custom format for messages returned by the Localization Module. Use this to modify or enhance how translated messages are structured, displayed, or processed before they are delivered to your application.

Example

Set the localizeFormatFunction property.

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

Set the localizeFormatFunction property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.localizeFormatFunction = function(defaultMessage, message, messageArguments){return '...'};

Get the localizeFormatFunction property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let localizeFormatFunction = dropdownlist.localizeFormatFunction;

messagesobject

Defines an object containing all text strings displayed by the widget, allowing for easy localization of the interface. This property can be used to get the current set of localizable strings or to provide custom translations for different languages. It works together with the locale property to determine which set of strings is shown to the user based on their selected language.

Default value

"en": {

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

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

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

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

"moduleUndefined": "Module is undefined.",

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

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

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

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

}

Example

Set the messages property.

 <smart-drop-down-list 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.","invalidNode":"{{elementType}}: Ungultiger Parameter '{{node}}' beim Aufruf von {{method}}."}}'></smart-drop-down-list>

Set the messages property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.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.","invalidNode":"{{elementType}}: Invalid parameter '{{node}}' when calling {{method}}."}};

Get the messages property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let messages = dropdownlist.messages;

namestring

Sets or retrieves the value of the element's name attribute. This attribute assigns an identifier to the element, which is used when submitting HTML forms to associate the element's data with a key in the form submission. The name attribute is essential for correctly processing form data on the server side.

Default value

Example

Set the name property.

 <smart-drop-down-list name='dropdown'></smart-drop-down-list>

Set the name property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.name = 'dropDown2';

Get the name property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let name = dropdownlist.name;

openedboolean

Specifies whether the popup is currently visible (open) or hidden (closed).

Default value

false

Example

Set the opened property.

 <smart-drop-down-list opened></smart-drop-down-list>

Set the opened property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.opened = false;

Get the opened property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let opened = dropdownlist.opened;

placeholderstring

Specifies the placeholder text that appears within the selection field of the element when no option has been chosen. This text provides guidance or an example to the user before a selection is made.

Default value

Try a demo showcasing the placeholder property.

Example

Set the placeholder property.

 <smart-drop-down-list placeholder='Choose:'></smart-drop-down-list>

Set the placeholder property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.placeholder = 'Submit';

Get the placeholder property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let placeholder = dropdownlist.placeholder;

readonlyboolean

Prevents any user interaction with the element, making it unresponsive to mouse, keyboard, touch, or other input events such as clicks, focus, or drag actions. While disabled, the element cannot be interacted with or activated by the user.

Default value

false

Example

Set the readonly property.

 <smart-drop-down-list readonly></smart-drop-down-list>

Set the readonly property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.readonly = false;

Get the readonly property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let readonly = dropdownlist.readonly;

rightToLeftboolean

Specifies or retrieves whether the element's text direction is set to right-to-left (RTL) alignment, which is typically used for languages such as Arabic or Hebrew. This property ensures that the element correctly displays content according to the reading direction of right-to-left locales.

Default value

false

Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property.

 <smart-drop-down-list right-to-left></smart-drop-down-list>

Set the rightToLeft property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.rightToLeft = false;

Get the rightToLeft property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let rightToLeft = dropdownlist.rightToLeft;

resizeIndicatorboolean

Specifies whether the resize indicator, located in the bottom-right corner of the dropdown, should be visible. This visual cue allows users to resize the dropdown if enabled. This property works in combination with the resizeMode setting, which controls the behavior of resizing.

Default value

false

Example

Set the resizeIndicator property.

 <smart-drop-down-list resize-indicator></smart-drop-down-list>

Set the resizeIndicator property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.resizeIndicator = false;

Get the resizeIndicator property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let resizeIndicator = dropdownlist.resizeIndicator;

resizeMode"none" | "horizontal" | "vertical" | "both"

Specifies whether the drop-down menu can be resized by the user. If resizing is enabled, a resize handle appears at either the top or bottom edge of the drop-down, allowing users to adjust its height interactively. This enhances usability by enabling users to customize the visible area of the drop-down content.

Allowed Values

"none" - Resizing the drop down is not allowed.
"horizontal" - Horizontal resizing of the drop down is allowed but not vertical.
"vertical" - Vertical resizing of the drop down is allowed but not horizontal.
"both" - Resizing the drop down is allowed in all directions.

Default value

"none"

Try a demo showcasing the resizeMode property.

Example

Set the resizeMode property.

 <smart-drop-down-list resize-mode='horizontal'></smart-drop-down-list>

Set the resizeMode property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.resizeMode = 'vertical';

Get the resizeMode property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let resizeMode = dropdownlist.resizeMode;

selectionDisplayMode"plain" | "placeholder" | "tokens"

Specifies the content or list of options that will appear in the drop-down selection field for users to choose from.

Allowed Values

"plain" - Default behavior. The selected item's label appears in the selection field inside the element.
"placeholder" - The placeholder is shown inside the selection field regardless of the current selection.
"tokens" - Token items are being appended to the selection field for each selected item. Tokens are used for multiple selection modes. When a token label is clicked the drop down opens and the corresponding item will be focused.

Default value

"plain"

Example

Set the selectionDisplayMode property.

 <smart-drop-down-list selection-display-mode='placeholder'></smart-drop-down-list>

Set the selectionDisplayMode property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.selectionDisplayMode = 'default';

Get the selectionDisplayMode property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let selectionDisplayMode = dropdownlist.selectionDisplayMode;

selectedIndexesnumber[]

Sets or retrieves the selected indexes. The selected indexes property is an array containing the numeric indexes of the items that are currently selected. You can assign an array of indexes to select specific items, or read this property to determine which items are currently selected.

Example

Set the selectedIndexes property.

 <smart-drop-down-list selected-indexes='[1,2,3]'></smart-drop-down-list>

Set the selectedIndexes property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.selectedIndexes = [4,5,6];

Get the selectedIndexes property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let selectedIndexes = dropdownlist.selectedIndexes;

selectedValuesstring[]

Gets or sets the indexes of selected items. The 'selected' values correspond to the indices of the items that are currently selected. When setting, provide an array of item indexes to indicate which items should be marked as selected. When getting, returns an array containing the indexes of the currently selected items.

Example

Set the selectedValues property.

 <smart-drop-down-list selected-values='["item 1"]'></smart-drop-down-list>

Set the selectedValues property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.selectedValues = ["item 2"];

Get the selectedValues property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let selectedValues = dropdownlist.selectedValues;

selectionMode"none" | "oneOrManyExtended" | "zeroOrMany" | "oneOrMany" | "zeroAndOne" | "zeroOrOne" | "one" | "checkBox" | "radioButton"

Specifies the maximum number of items that a user is allowed to select at one time. If set to 1, only single selection is permitted; higher values allow for multiple selections up to the defined limit.

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 drop down. One, many or zero items can be selected.
"radioButton" - A radio button appears next to every List item inside the drop down. Only one item can be selected or one item per group if grouped is enabled.

Default value

"zeroAndOne"

Example

Set the selectionMode property.

 <smart-drop-down-list selection-mode='none'></smart-drop-down-list>

Set the selectionMode property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.selectionMode = 'oneOrManyExtended';

Get the selectionMode property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let selectionMode = dropdownlist.selectionMode;

sortedboolean

Specifies whether the items are arranged in alphabetical order. If set to true, the items will be sorted alphabetically (A–Z); if false, the original order of the items will be preserved.

Default value

false

Try a demo showcasing the sorted property.

Example

Set the sorted property.

 <smart-drop-down-list sorted></smart-drop-down-list>

Set the sorted property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.sorted = false;

Get the sorted property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let sorted = dropdownlist.sorted;

sortDirectionstring

Specifies the sorting order for data:
- Use "asc" for ascending order (e.g., A-Z, 0-9).
- Use "desc" for descending order (e.g., Z-A, 9-0).

Default value

"asc"

Example

Set the sortDirection property.

 <smart-drop-down-list sort-direction='desc'></smart-drop-down-list>

Set the sortDirection property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.sortDirection = 'asc';

Get the sortDirection property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let sortDirection = dropdownlist.sortDirection;

themestring

Specifies the visual theme to be applied to the element. Themes control the overall appearance, including colors, fonts, and styles, ensuring a consistent and customized look for the element.

Default value

Example

Set the theme property.

 <smart-drop-down-list theme='blue'></smart-drop-down-list>

Set the theme property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.theme = 'red';

Get the theme property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let theme = dropdownlist.theme;

tokenTemplateany

Defines a custom template for rendering each token's content when the selectionDisplayMode property is set to 'tokens'. This allows you to control the appearance and structure of individual tokens displayed in the selection area.

Try a demo showcasing the tokenTemplate property.

Example

Set the tokenTemplate property.

 <smart-drop-down-list token-template='tokenTemplate'></smart-drop-down-list>

Set the tokenTemplate property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.tokenTemplate = null;

Get the tokenTemplate property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let tokenTemplate = dropdownlist.tokenTemplate;

unfocusableboolean

If set to true, this property prevents the element from receiving keyboard focus, making it impossible for users to navigate to the element using the Tab key or other keyboard navigation methods.

Default value

false

Example

Set the unfocusable property.

 <smart-drop-down-list unfocusable></smart-drop-down-list>

Set the unfocusable property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.unfocusable = false;

Get the unfocusable property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let unfocusable = dropdownlist.unfocusable;

valueany

Sets or retrieves the current selection values. When called, this function returns an array of objects representing the selected items, where each object has the following structure: { label: string, value: any }.

Return type: Array<{ label: string, value: any }>.

Example

Set the value property.

 <smart-drop-down-list value='1'></smart-drop-down-list>

Set the value property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.value = 2;

Get the value property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let value = dropdownlist.value;

valueMemberstring

Determines which property of each item object should be used as the item's value. The value specified by valueMember will be stored as the value of the ListBox item. This property is particularly useful when populating the ListBox from a JSON dataSource, and you want to designate a specific field from each JSON item (such as id, code, or another unique identifier) to serve as the item's value. Similar to groupMember, valueMember helps map a property in your JSON objects directly to the ListBox value, ensuring the correct data is referenced and used when working with item selections or submissions.

Default value

""""

Example

Set the valueMember property.

 <smart-drop-down-list value-member='value'></smart-drop-down-list>

Set the valueMember property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.valueMember = 'newValue';

Get the valueMember property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let valueMember = dropdownlist.valueMember;

verticalScrollBarVisibility"auto" | "disabled" | "hidden" | "visible"

Controls whether the vertical scroll bar is displayed within the container. Set this property to enable, disable, or automatically show the scroll bar based on the content's height relative to 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"

Example

Set the verticalScrollBarVisibility property.

 <smart-drop-down-list vertical-scroll-bar-visibility='hidden'></smart-drop-down-list>

Set the verticalScrollBarVisibility property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.verticalScrollBarVisibility = 'visible';

Get the verticalScrollBarVisibility property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let verticalScrollBarVisibility = dropdownlist.verticalScrollBarVisibility;

virtualizedboolean

Specifies whether virtualization is enabled for the dropdown component. When virtualization is enabled, the dropdown can efficiently handle and display a large number of items—such as one million—by rendering only the visible items rather than all items at once. This significantly improves performance and responsiveness, even when working with vast datasets.

Default value

false

Example

Set the virtualized property.

 <smart-drop-down-list virtualized></smart-drop-down-list>

Set the virtualized property by using the HTML Element's instance.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 dropdownlist.virtualized = false;

Get the virtualized property.

 const dropdownlist = document.querySelector('smart-drop-down-list');

 let virtualized = dropdownlist.virtualized;

Events

actionButtonClickCustomEvent

This event is triggered when the user clicks the action button. Note that the action button is only visible if the dropDownOpenMode property is set to 'dropDownbutton'. If dropDownOpenMode is set to any other value, the action button will be hidden and this event will not be triggered.

Bubbles Yes
Cancelable No
Interface CustomEvent
Event handler property onActionButtonClick

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.

Example

Set up the event handler of actionButtonClick event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('actionButtonClick', function (event) {
	// event handling code goes here.
})

changeCustomEvent

This event is triggered whenever the user modifies their current selection, such as selecting or deselecting one or more items within a list, dropdown, or input field. It fires immediately after the selection change has occurred, allowing you to respond dynamically to user interactions.

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.

Example

Set up the event handler of change event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('change', function (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.
})

closeCustomEvent

This event is triggered when the dropdown list is closed, either by selecting an item, clicking outside the dropdown, or pressing the Escape key. It allows you to execute custom actions after the dropdown is no longer visible to the user.

Bubbles Yes
Cancelable No
Interface CustomEvent
Event handler property onClose

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.

Example

Set up the event handler of close event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('close', function (event) {
	// event handling code goes here.
})

closingCustomEvent

This event is triggered just before the drop-down list is about to close. By handling this event, you have the opportunity to prevent the drop-down from closing by calling event.preventDefault() within your event handler function. This is useful if you need to perform additional validation or asynchronous operations before allowing the drop-down to close.

Bubbles Yes
Cancelable Yes
Interface CustomEvent
Event handler property onClosing

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.

Example

Set up the event handler of closing event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('closing', function (event) {
	// event handling code goes here.
})

dropDownButtonClickCustomEvent

This event is triggered when the user clicks on the dropdown button, allowing you to execute custom logic in response to the user's action of opening or interacting with the dropdown menu.

Bubbles Yes
Cancelable No
Interface CustomEvent
Event handler property onDropDownButtonClick

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.

Example

Set up the event handler of dropDownButtonClick event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('dropDownButtonClick', function (event) {
	// event handling code goes here.
})

itemClickCustomEvent

This event is triggered whenever a user clicks on an individual item within the interface. It provides contextual information about the selected item, allowing you to perform actions such as displaying details, initiating edits, or handling custom behaviors in response to the user's selection.

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.

Example

Set up the event handler of itemClick event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('itemClick', function (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.
})

openCustomEvent

This event is triggered whenever the dropdown list component becomes visible to the user, such as when a user clicks on the dropdown control to display its list of selectable options.

Bubbles Yes
Cancelable No
Interface CustomEvent
Event handler property onOpen

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.

Example

Set up the event handler of open event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('open', function (event) {
	// event handling code goes here.
})

openingCustomEvent

This event is triggered immediately before the dropdown list is displayed. Within the event handler, you can prevent the dropdown from opening by calling event.preventDefault(). This provides an opportunity to execute custom logic or perform validation before allowing the dropdown to appear.

Bubbles Yes
Cancelable Yes
Interface CustomEvent
Event handler property onOpening

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.

Example

Set up the event handler of opening event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('opening', function (event) {
	// event handling code goes here.
})

resizeStartCustomEvent

This event is triggered when the user initiates the action of resizing the dropdown menu. It occurs as soon as the user begins to adjust the dropdown's dimensions, such as by clicking and dragging the resize handle or border.

Bubbles Yes
Cancelable No
Interface CustomEvent
Event handler property onResizeStart

Arguments

evCustomEvent

ev.detailObject

ev.detail.position - An object containing the current left and top positions of the drop down.

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.

Example

Set up the event handler of resizeStart event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('resizeStart', function (event) {
    const detail = event.detail,
        position = detail.position;

	// event handling code goes here.
})

resizeEndCustomEvent

This event is triggered after the user has completed resizing the dropdown component. It fires once the resize action has ended, allowing you to perform actions such as updating the layout or saving the new dimensions of the dropdown.

Bubbles Yes
Cancelable No
Interface CustomEvent
Event handler property onResizeEnd

Arguments

evCustomEvent

ev.detailObject

ev.detail.position - An object containing the current left and top positions of the drop down.

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.

Example

Set up the event handler of resizeEnd event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('resizeEnd', function (event) {
    const detail = event.detail,
        position = detail.position;

	// event handling code goes here.
})

scrollBottomReachedCustomEvent

This event is triggered when the user scrolls to the bottom of the dropDown list, indicating that all available options have been displayed. It can be used to load additional items dynamically (infinite scroll) or to perform specific actions once the end of the list is reached.

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.

Example

Set up the event handler of scrollBottomReached event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('scrollBottomReached', function (event) {
	// event handling code goes here.
})

scrollTopReachedCustomEvent

This event is triggered when the user scrolls to the very top (beginning) of the drop-down list, indicating that there are no more items above the currently visible options.

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.

Example

Set up the event handler of scrollTopReached event.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.addEventListener('scrollTopReached', function (event) {
	// event handling code goes here.
})

Methods

appendChild( node: Node): T

Arguments

nodeNode

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

ReturnsNode

add( item: any): void

Adds one or more new items to the collection, array, or list. This action typically appends the provided item(s) to the existing data structure, increasing its size. Specify the items to be added as input parameters.

Arguments

itemany

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

Invoke the add method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.add("'New item'");

Try a demo showcasing the add method.

clearItems(): void

Removes all items from the drop-down list, clearing its contents and leaving the list empty. This action ensures that no selectable options remain within the drop-down component.

Invoke the clearItems method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.clearItems();

clearSelection(): void

Deselects all currently selected items, ensuring that no items remain selected.

Invoke the clearSelection method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.clearSelection();

close(): void

Closes the currently open dropdown list, hiding all available options from view and returning the dropdown to its default collapsed state. This action does not select or modify any options within the list.

Invoke the close method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.close();

Try a demo showcasing the close method.

dataBind(): void

Initiates the data binding process, updating the user interface with the latest values from the data source. This method can be used to refresh or re-sync the UI whenever the underlying data changes, ensuring that displayed information remains current and accurate.

Invoke the dataBind method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.dataBind();

Try a demo showcasing the dataBind method.

ensureVisible( item: HTMLElement | string): void

Scrolls the view to bring the specified item into the visible area of its container, ensuring that the item is fully or partially visible to the user. This enables users to locate and interact with the desired item without manual scrolling.

Arguments

itemHTMLElement | string

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

Invoke the ensureVisible method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.ensureVisible("'item1'");

getItem( value: string): HTMLElement

Returns the selected item instance from the dropDown list. This method retrieves the full object representing the currently chosen entry, including all associated properties and values, allowing further manipulation or data access within your application.

Arguments

valuestring

The value of an item from the drop down list.

ReturnsHTMLElement

Invoke the getItem method.

const dropdownlist = document.querySelector('smart-drop-down-list');
const result = dropdownlist.getItem("First");

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

Inserts a new item into the collection at the specified index, shifting existing items at and after that position one place to the right.

Arguments

positionnumber

The position where the item must be inserted.

valueany

The value of the new item.

Invoke the insert method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.insert(5,"'New item'");

Try a demo showcasing the insert method.

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

Arguments

nodeNode

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

referenceNodeNode | null

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

ReturnsNode

open(): void

Displays the drop-down list, allowing users to view and select from the available options.

Invoke the open method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.open();

Try a demo showcasing the open method.

removeAt( position: number): void

Removes the item located at the specified index or position within the collection, shifting any subsequent items to fill the gap. If the specified position is out of range, no changes are made to the collection.

Arguments

positionnumber

The position of the removed item.

Invoke the removeAt method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.removeAt(5);

Try a demo showcasing the removeAt method.

removeChild( node: Node): T

Arguments

nodeNode

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

ReturnsNode

select( item: string | HTMLElement): void

Selects a specific item from the dropdown list based on the user's input or selection criteria. This action updates the dropdown's displayed value to the chosen item and may trigger any associated event handlers or callbacks.

Arguments

itemstring | HTMLElement

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

Invoke the select method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.select("'First Item'");

unselect( item: string | HTMLElement): void

Removes the currently selected item from the dropdown list, restoring the dropdown to its unselected or default state. This action ensures that no item remains highlighted or chosen within the dropdown component.

Arguments

itemstring | HTMLElement

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

Invoke the unselect method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.unselect("'First Item'");

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

Updates the selected item in the dropDown list with new data or values. This action modifies the existing item rather than adding a new entry or removing an existing one, ensuring that the dropDown reflects the most current information.

Arguments

positionnumber

The position where the item must be updated.

valueany

The value of the updated item.

Invoke the update method.

const dropdownlist = document.querySelector('smart-drop-down-list');
dropdownlist.update(5,"'Updated item'");

Try a demo showcasing the update method.

CSS Variables

--smart-drop-down-list-default-widthvar()

Default value

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

smartDropDownList, smartComboBox default width

--smart-drop-down-list-default-heightvar()

Default value

"var(--smart-editor-height)"

smartDropDownList, smartComboBox default height

--smart-drop-down-list-drop-down-widthvar()

Default value

"initial"

smartDropDownList drop down width

--smart-drop-down-list-drop-down-heightvar()

Default value

"auto"

smartDropDownList drop down height

alternationIndexnumber

Default value

-1

colorstring

Default value

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

Default value

"plain"

groupedboolean

Default value

false

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

selectedboolean

Default value

false

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

valuestring

Default value

labelstring

Default value

detailsstring

Default value

groupstring

Default value

hiddenboolean

Default value

false

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

readonlyboolean

Default value

false

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

DropDownList Javascript API

autoCloseDelaynumber

Default value

Example

dataSourceany

Example

disabledboolean

Default value

Example

displayLoadingIndicatorboolean

Default value

Example

displayMemberstring

Default value

Example

dropDownAppendTostring

Default value

Example

dropDownButtonPosition"left" | "right" | "top" | "bottom"

Default value

Example

dropDownHeightstring | number

Default value

Example

dropDownMaxHeightstring | number

Default value

Example

dropDownMaxWidthstring | number

Default value

Example

dropDownMinHeightstring | number

Default value

Example

dropDownMinWidthstring | number

Default value

Example

dropDownOpenMode"none" | "default" | "dropDownButton" | "auto"

Default value

Example

dropDownOverlayboolean

Default value

Example

dropDownPlaceholderstring

Default value

Example

dropDownPosition"auto" | "top" | "bottom" | "overlay-top" | "overlay-center" | "overlay-bottom" | "center-bottom" | "center-top"

Default value

Example

dropDownWidthstring | number

Default value

Example

filterableboolean

Default value

Example

filterInputPlaceholderstring

Default value

Example

filterMode"contains" | "containsIgnoreCase" | "custom" | "doesNotContain" | "doesNotContainIgnoreCase" | "equals" | "equalsIgnoreCase" | "startsWith" | "startsWithIgnoreCase" | "endsWith" | "endsWithIgnoreCase"

Default value

Example

filterCallbackfunction | null

Example

groupedboolean

Default value

Example

groupMemberstring | null

Example