ComboBox — Smart UI JavaScript API

ComboBox — 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>ComboBox - JavaScript Quick Start</title>
  <link rel="stylesheet" href="./node_modules/smart-webcomponents/source/styles/smart.default.css" />
</head>
<body>
  <smart-combo-box id="demo-combobox"></smart-combo-box>

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

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

      el.dataSource = ['Espresso', 'Latte', 'Cappuccino', 'Mocha'];
      el.autoComplete = 'auto';
      el.selectedIndexes = [1];

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

Developer Quick Reference

Component: ComboBox   Framework: JavaScript   Selector: smart-combo-box

API counts: 65 properties, 16 methods, 11 events

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

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

Common events: change, close, closing, itemClick, open, opening

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

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

Class

ComboBox
ListItem
ListItemsGroup

ComboBox

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

Selector

smart-combo-box

Quick picks

changeclosedataSourcedisableditemsopenvalue

Properties

AautoCloseDelayThis property is applicable only when dropDownOpenMode is set to 'auto'. It specifies the amount of time (in milliseconds) the dropdown will remain open after the pointer leaves the element, before it automatically closes. If the pointer is not hovering over the dropdown or its trigger element, the dropdown will close after this delay.
AautoCompleteSpecifies the autocomplete mode for the input field. The selected mode defines how the component filters and displays items from the dataSource, showing only those entries that match the user's input according to the chosen matching strategy. This setting directly impacts the suggestions presented to the user as they type.
AautoCompleteDelaySpecifies the amount of time, in milliseconds, to wait after the user input before displaying the dropdown list of autocomplete suggestions. This delay helps control how quickly the suggestions appear, allowing for smoother user experience and reducing unnecessary searches as the user types.
AautoOpenShortcutKeyEnables users to specify one or more custom key names that will trigger the opening of the popup when pressed. This allows for flexible keyboard shortcuts tailored to user preferences or application requirements.
DdataSourceSpecifies the source of data to populate the ComboBox. The dataSource can be provided in several formats:- An array of strings or numbers, where each item becomes a selectable option in the ComboBox.- An array of objects, where each object represents a list item and its properties define the displayed information and associated value (e.g., label for display text, value for the underlying value, and optionally group to categorize items).- A callback function that returns an array of items in either of the above formats, enabling dynamic or asynchronous data loading.This flexible dataSource configuration allows the ComboBox to support simple lists, categorized lists, or dynamically retrieved data.
DdisabledControls whether the combo box is active or inactive. When enabled, users can interact with the combo box to select or enter a value. When disabled, the combo box is non-interactive and appears grayed out, preventing any user input or selection.
DdisplayLoadingIndicatorSpecifies whether a visual indicator (such as a loading spinner or progress bar) will be displayed while filtering data locally or when retrieving items from a remote source. This helps inform users that a filtering operation or data fetch is in progress.
DdisplayMemberSets or retrieves the displayMember property. The displayMember property defines the specific field name within each data object in the collection provided by the 'dataSource' property. This field's value is used for displaying items in the UI component, allowing you to control which attribute of your data objects is shown to the user.
DdropDownAppendToSpecifies the parent container for the dropdown element. The dropDownAppendTo property accepts a CSS selector string, an element's ID, the string value 'body', or a direct reference to an HTML element. By default, the dropdown is appended to its original parent in the DOM. However, if one of the containing elements has CSS properties (such as overflow: hidden) that restrict the dropdown's visibility, you can set this property—commonly to 'body'—to append the dropdown directly to the <body> element and ensure it displays properly.Possible values:- A CSS selector string (e.g., '.container' or '#mainDiv')- The string 'body'- A direct reference to an existing HTML element- An element's ID (as a string)- null (to reset and move the dropdown back to its original parent)This property improves compatibility in layouts with restricted overflow by allowing the dropdown to be rendered in a container of your choosing. Resetting dropDownAppendTo to null restores the dropdown to its initial placement within the DOM.
DdropDownButtonPositionSpecifies the location of the dropdown button relative to its associated input field or container. Possible positions may include "left," "right," "top," or "bottom," allowing developers to control where the dropdown button appears in the user interface.
DdropDownHeightSpecifies the height of the dropdown menu. By default, this property is set to an empty string, which means the dropdown’s height will be determined by the corresponding CSS variable. If a specific value is provided, it will override the CSS variable and set the dropdown height explicitly.
DdropDownMaxHeightSpecifies the maximum height of the dropdown menu. By default, this value is set to an empty string, which means the dropdown's max-height will be controlled by a CSS variable instead of an explicit value. If you provide a specific value (e.g., "300px" or "50vh"), it will override the default CSS variable and directly set the maximum height of the dropdown.
DdropDownMaxWidthDefines the maximum width of the dropdown menu. By default, this value is set to an empty string, which means the dropdown's maximum width will be determined by a corresponding CSS variable. If a specific value is provided (e.g., "300px" or "50%"), it will override the CSS variable and directly set the maximum width of the dropdown.
DdropDownMinHeightDefines the minimum height of the dropdown component. By default, this property is set to an empty string, which means the dropdown's minimum height is determined by a corresponding CSS variable. If a specific value is provided for this property, it will override the CSS variable and explicitly set the dropdown's minimum height.
DdropDownMinWidthSpecifies the minimum width of the dropdown component. By default, this property is set to an empty string (""). When left unset, the dropdown’s minimum width is determined by a CSS variable, allowing for flexible styling through external stylesheets. To override the CSS value, assign a specific width value (e.g., "200px" or "10rem") to this property.
DdropDownOpenModeSpecifies the direction or animation in which the dropdown menu will appear when activated, such as opening upwards, downwards, or with a specific transition effect.
DdropDownOverlayIf this property is enabled, opening the element's dropdown will insert a transparent overlay between the dropdown and the rest of the document. This overlay covers the entire viewport except for the dropdown itself, capturing all click events outside the dropdown. As a result, any clicks outside the popup will interact with the overlay instead of other elements on the page, allowing you to reliably detect and handle outside clicks (such as to close the dropdown) without unintentionally triggering other DOM elements.
DdropDownPlaceholderSpecifies the text or content to be shown in the dropdown as a placeholder when the dropdown contains no selectable items. This placeholder provides guidance or context to the user, indicating that there are currently no available options.
DdropDownPositionSpecifies the placement of the dropdown menu relative to its trigger element when opened (e.g., above, below, left, or right). This setting controls where the dropdown appears on the screen in relation to the element that activates it.
DdropDownWidthSpecifies the width of the dropdown menu. By default, this property is set to an empty string, allowing the dropdown's width to be determined by the associated CSS variable (typically via custom properties or theme settings). If a value is provided, it overrides the CSS variable and directly sets the dropdown's width.
EescKeyModeSpecifies how the element should respond when the Escape key is pressed by the user. This property allows you to define actions such as closing a modal, dismissing a dialog, or triggering a custom event when the Escape key is detected while the element is focused or active.
FfilterableSpecifies whether the filtering feature is active. When set to true, users can apply filters to narrow down displayed data; when false, filtering options are disabled and all data is shown without restriction.
FfilterInputPlaceholderSpecifies the placeholder text displayed inside the dropdown list’s filter input field, guiding users on what to enter when searching or filtering options.
FfilterModeSpecifies the filtering behavior for the Combo Box, controlling how user input is matched against the available options (e.g., contains, starts with, or exact match). This property determines which options are displayed in the dropdown list as the user types.
GgroupedWhen enabled, this option automatically groups the items based on the first letter of each item's value or label. Note: This grouping feature is only available if the dataSource does not already include predefined groups. If the dataSource is already grouped, this setting will have no effect.
GgroupMemberSpecifies which attribute of the dataSource object should be used to group items in the ListBox. By default, if this property (groupMember) is not set, the ListBox will use the 'group' property from each dataSource item to organize groups. This property is particularly useful when loading data from a JSON file, allowing you to designate a specific property from your data objects to determine the grouping of items—especially if your JSON structure uses a different property name for grouping.
HhintDisplays supplementary helper text beneath the element. This hint is visible exclusively when the element is in focus, providing contextual guidance to users as they interact with the field.
HhorizontalScrollBarVisibilityControls whether the horizontal scroll bar is displayed within the dropdown menu when the content exceeds the available width.
IincrementalSearchDelayThe 'IncrementalSearchDelay' property defines the duration, in milliseconds, to wait after the user stops typing before clearing the previous search query. This timer begins as soon as the user finishes typing. During this delay period, no new search query will be initiated. Only after the specified delay has elapsed will the current search input be cleared, allowing a new search query to be started. This helps to optimize performance and user experience by preventing unnecessary or premature queries while the user is still entering their search terms.
IincrementalSearchModeConfigures or retrieves the current mode of incremental search. By default, incremental search is enabled, allowing users to type while the dropdown is focused to quickly filter and highlight matching options. Modifying this setting controls how user input is processed for searching within the dropdown list.
IinputMemberRepresents the property name of a List item whose value will be displayed in the input field when a ListItem is selected. This allows developers to control which property of each item is shown in the input, such as displaying the item's value instead of its label. By default, the label property is used for display. This option is useful when you want to customize the displayed content, for example, to show a unique identifier or value rather than the descriptive label.
IinputPurposeSpecifies the expected type of information for the input field and informs the browser about the nature of the data to be entered. This guidance allows user agents (such as browsers and password managers) to determine if they can provide automated assistance—like autofilling relevant values—when the element is used in a form. The value assigned to this property directly maps to the standard HTML autocomplete attribute. Common values include 'on' (enable autocomplete), 'off' (disable autocomplete), 'name' (full name), 'organization' (company or organization), 'email', 'street-address', and many others, as specified by the HTML standard. Using an appropriate value improves user experience, enhances accessibility, and helps maintain privacy and security standards within web forms.
IitemHeightSpecifies the height (in pixels) for each list item when rendering the list. This property is only applicable when list virtualization is enabled, as it helps optimize rendering performance by allowing the component to calculate and render only the visible items.
IitemMeasureModeSpecifies the algorithm used to calculate the width of each item. This setting determines how the width of an item is measured, such as using the item's intrinsic content size, a fixed value, or a percentage of the container. Adjust this parameter to control how item widths are determined within the layout.
IitemsA getter method that retrieves and returns an array containing all list ('li') elements currently present within the dropdown menu. This allows you to easily access and manipulate every item displayed in the dropdown.
IitemTemplateThe itemTemplate property is a string that specifies the ID of an HTMLTemplateElement present in the DOM. This template is used to define and customize the structure and content of individual list items, allowing developers to control how each item appears when rendered in the list.
LlabelDisplays a small text label positioned above the element, typically used to provide context, instructions, or additional information to users.
LloadingIndicatorPlaceholderSpecifies the text that appears alongside the loading indicator when the loader is visible and positioned at the top or bottom of the component. This text provides users with contextual information or status updates during loading.
LloadingIndicatorPositionSpecifies the exact location on the user interface where the loading indicator will be displayed, such as at the top, center, or bottom of the screen or component.
LlocaleSpecifies or retrieves the current language setting for the component. This property determines which language is used when displaying content from the messages property, allowing for localization and internationalization of displayed messages. Set this property to a supported language code (e.g., "en", "fr") to load the corresponding translations from the messages object.
LlocalizeFormatFunctionA callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this callback to modify message text, apply dynamic values, or implement custom formatting logic before the localized messages are delivered to your application.
MmaxLengthSpecifies the maximum number of characters that can be entered into the input field. Any additional characters beyond this limit will not be accepted. This helps enforce data validation and consistency for user input.
MmessagesSpecifies or retrieves an object containing localized string values used within the widget’s user interface. This property enables the customization and translation of UI text for different languages or regions. It is intended to be used together with the locale property, allowing you to easily provide or update localized strings according to the selected locale.
MminLengthSpecifies the minimum number of characters a user must enter in the input field before the autocomplete feature is activated and suggestions are displayed.
NnameSets or retrieves the value of the element's name attribute. The name attribute uniquely identifies form elements when submitting HTML forms, allowing the form data to be organized and accessed by name on the server side. This attribute is essential for grouping form controls and accurately transmitting user input during form submission.
OopenedSpecifies whether the popup is currently visible (open) or hidden (closed) in the user interface.
PplaceholderSpecifies the placeholder text that appears inside the input field when it is empty, providing guidance or example content to the user.
RreadonlyPrevents any user interactions with the element, including clicking, tapping, selecting, hovering, or focusing. While this is enabled, the element will not respond to mouse, keyboard, or touch events, effectively making it non-interactive for users.
RresizeIndicatorControls the visibility of the resize indicator located in the bottom-right corner of the dropdown component. When this property is set to true, users will see a handle allowing them to resize the dropdown area. This property should be used together with the resizeMode property to define both the availability and behavior of the resizing feature.
RresizeModeSpecifies whether the drop-down menu is resizable by the user. If resizing is enabled, a resize bar will be displayed along the top or bottom edge of the drop-down, allowing users to click and drag to adjust its height. Disabling this option removes the resize bar and prevents any manual resizing of the drop-down component.
RrightToLeftSpecifies or retrieves a value that determines whether the element’s text direction is set to support right-to-left (RTL) languages, such as Arabic or Hebrew. When enabled, the element and its content are aligned according to RTL formatting, ensuring proper display for locales that use right-to-left scripts.
SselectedIndexesSets or retrieves the selected indexes. The selected indexes property is an array containing the numeric indexes of the items that are currently selected. Each value in the array corresponds to the position of a selected item within the overall list or collection. Assigning a new array to this property updates the selection state to match the specified indexes; retrieving it returns the current selection as an array of indexes.
SselectedValues "Sets or retrieves the currently selected indexes. The 'selected' property holds an array of the indices corresponding to the items that are marked as selected. When setting this property, provide an array of indexes to specify which items should be selected. When getting this property, it returns the array of indexes for the currently selected items."
SselectionDisplayModeSpecifies the content or value that will appear within the input field, either as a default value, user-entered data, or dynamically generated content. This setting controls what the user sees and interacts with inside the input element.
SselectionModeSpecifies the maximum number of items that a user is allowed to select at one time. If this value is set to 1, only single selection is permitted; higher values allow multiple selections up to the defined limit.
SsortDirectionSpecifies the sorting order for data, allowing you to choose between ascending ("asc") for lowest-to-highest or alphabetical A–Z sorting, and descending ("desc") for highest-to-lowest or Z–A sorting.
SsortedSpecifies whether the items are arranged in alphabetical order. If set to true, the items will be sorted alphabetically; if false, the original order will be preserved.
TthemeSpecifies the visual theme to be applied to the element. The selected theme controls the element’s appearance, including colors, fonts, and other stylistic properties, ensuring a consistent look and feel across the user interface.
TtokenTemplateDefines the custom content to display within each token when the selectionDisplayMode is set to "tokens". Tokens visually represent selected items in a multi-select interface and are only applicable when multiple selection is enabled. Use this option to customize how each token appears, such as displaying specific text, icons, or additional data for each selected item.
UunfocusableIf set to true, the element will not be able to receive keyboard or mouse focus, making it inaccessible via tab navigation or programmatic focus methods.
UunlockKeySets or retrieves the unlockKey, a unique value required to grant access to the product’s premium features or activate its full functionality.
VvalueProvides functionality to retrieve (get) or assign (set) the current value of the property. When used as a getter, it returns the property's current value. When used as a setter, it updates the property with the specified value.
VvalueMemberSpecifies which property of each item object should be used as the value for that item. The value designated by valueMember will be stored in the item's value field. This property functions similarly to groupMember, but is focused on identifying the value rather than the group. valueMember is particularly useful when populating a ListBox from a JSON data source, as it allows you to specify which property of your data objects should serve as the unique value for each item in the ListBox.
VverticalScrollBarVisibilityControls whether the vertical scroll bar is displayed within the content area, allowing users to scroll vertically when the content extends beyond the visible region.
VvirtualizedDetermines whether virtualization is enabled for the ComboBox. When virtualization is enabled, the ComboBox can efficiently display a very large number of items—such as a million—by only rendering the visible items in the ListBox and dynamically loading items as needed. This significantly improves performance and reduces memory usage, especially with large data sets.

Events

CchangeThis event is triggered whenever the user changes the current selection, such as highlighting different text or selecting a new item in a list. It allows you to detect and respond to updates in the selected content or options within the interface.
CcloseThis event is triggered when the drop-down list is closed, either by the user selecting an option or by clicking outside the menu. It occurs after the drop-down menu is no longer visible, allowing you to perform actions in response to the menu's closure.
CclosingThis event is triggered right before the dropdown list is about to close, providing an opportunity to intervene. By calling event.preventDefault() within the event handler, you can cancel the closing operation, allowing you to perform validation, display a confirmation dialog, or execute custom logic before the dropdown is closed.
IitemClickThis event is triggered whenever a user clicks on a specific item, allowing you to execute custom actions in response to the user's selection. The event provides context about the clicked item, enabling you to access its properties or perform related updates within your application.
OopenThis event is triggered whenever the dropdown list becomes visible to the user, such as when the user clicks or interacts with the control to expand and display the list of available options. Use this event to execute custom logic when the dropdown menu is opened.
OopeningThis event is triggered immediately before the dropdown list is displayed to the user. Within the event handler, you can prevent the dropdown from opening by calling event.preventDefault(). This allows you to implement custom logic to conditionally allow or block the opening of the dropdown, such as validating conditions or managing user permissions before the list is shown.
RresizeEndThis event is triggered after the user has completed resizing the dropdown menu, signaling that the resizing action has ended and the new dimensions have been set.
RresizeStartThis event is triggered when the user initiates the resizing action on the dropdown component, such as clicking and dragging a resize handle. It allows developers to detect the exact moment when a resize operation on the dropdown begins.
SscrollBottomReachedThis 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 detect when additional data should be loaded or when no further options remain in the dropdown.
SscrollTopReachedThis event is triggered when the user scrolls to the very beginning (top) of the dropdown list, indicating that no more items are available above the current view.
TtokenClickThis event is triggered when a token item (also known as a 'pill') is clicked by the user. By handling this event, developers have the opportunity to intercept the default action that would normally occur when the token is clicked—such as opening a dropdown or performing another related operation. To prevent the default behavior from executing, call event.preventDefault() within your event handler function."

Methods

AaddCreates and appends one or more new items to the collection or list.
CclearItemsRemoves all existing items from the dropdown list, resulting in an empty list with no selectable options displayed to the user.
CclearSelectionDeselects all currently selected items, ensuring that no items remain selected. This action clears any existing selections and resets the selection state.
CcloseCloses the currently open drop-down list, hiding all available options from view and returning the component to its collapsed state. This action ensures that the drop-down menu is no longer visible to the user.
DdataBindInitiates a data binding process, connecting UI components to the underlying data source. This method refreshes the data source, ensuring that any changes made to the data are reflected in the user interface. It can be used to update displayed information after modifying, adding, or deleting data.
EensureVisibleScrolls the target item into view within its container, automatically adjusting the scroll position as needed to make sure the entire item is fully visible to the user.
GgetItemReturns a specific item instance from the dropDown list, allowing you to access the properties and methods of the selected list item. This can be used to retrieve information about the item, such as its value, label, or index within the dropDown.
IinsertInserts a new item into the array at the specified index position, shifting existing elements to the right to accommodate the new item.
OopenDisplays and expands the drop-down list, making all available options visible for selection.
RremoveAtRemoves the item located at the specified index or position within a collection (such as an array or list). After removal, the collection is updated so that subsequent items shift to fill the gap, ensuring contiguous indexing.
SselectSelects a specified item from the dropdown list, allowing users to choose one option from the available choices. This action updates the dropdown’s current selection and can trigger any associated event handlers or changes in the application’s state.
UunselectDeselects a specified item from the dropdown list, removing its selected state and reverting the dropdown to reflect that the item is no longer chosen by the user.
UupdateUpdates the selected item in the dropDown list with new data or attributes. This action modifies the existing item rather than adding or removing items from the list, ensuring that any changes are reflected immediately in the user interface. Specify the target item and the updated values to complete the operation.

Properties

autoCloseDelayThis property is applicable only when dropDownOpenMode is set to 'auto'. It specifies the amount of time (in milliseconds) the dropdown will remain open after the pointer leaves the element, before it automatically closes. If the pointer is not hovering over the dropdown or its trigger element, the dropdown will close after this delay.number

This property is applicable only when dropDownOpenMode is set to 'auto'. It specifies the amount of time (in milliseconds) the dropdown will remain open after the pointer leaves the element, before it automatically closes. If the pointer is not hovering over the dropdown or its trigger element, the dropdown will close after this delay.

Default value

100

Examples

Markup and runtime examples for autoCloseDelay:

HTML:

<smart-combo-box auto-close-delay="50"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.autoCloseDelay = 200;

Read the current value:

const el = document.querySelector('smart-combo-box');
const autoCloseDelay = el.autoCloseDelay;

autoCompleteSpecifies the autocomplete mode for the input field. The selected mode defines how the component filters and displays items from the dataSource, showing only those entries that match the user's input according to the chosen matching strategy. This setting directly impacts the suggestions presented to the user as they type."none" | "auto" | "inline" | "manual"

Specifies the autocomplete mode for the input field. The selected mode defines how the component filters and displays items from the dataSource, showing only those entries that match the user's input according to the chosen matching strategy. This setting directly impacts the suggestions presented to the user as they type.

Allowed Values

  • "none" - Auto complete is disabled.
  • "auto" - When the input matches one or many items from the dataSource the drop down opens and displays the matched items. The first suggested item is automatically highlighted as selected and becomes the value of the textbox when the combobox loses focus unless the user chooses a different item or changes the character string in the textbox.
  • "inline" - When the input matches one or many items from the dataSource the drop down opens and displays the matched items. The first suggested item is automatically highlighted as selected and becomes the value of the textbox when the combobox loses focus unless the user chooses a different item or changes the character string in the textbox. In addition to that a completion helper that appears next to the input cursor in the input. This helper shows the first possible match by completing the input text.
  • "manual" - When the input matches one or many items from the dataSource the drop down opens and displays the matched items.

Default value

"none"
Try a demo showcasing the autoComplete property.

Examples

Markup and runtime examples for autoComplete:

HTML:

<smart-combo-box auto-complete="auto"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.autoComplete = "manual";

Read the current value:

const el = document.querySelector('smart-combo-box');
const autoComplete = el.autoComplete;

autoCompleteDelaySpecifies the amount of time, in milliseconds, to wait after the user input before displaying the dropdown list of autocomplete suggestions. This delay helps control how quickly the suggestions appear, allowing for smoother user experience and reducing unnecessary searches as the user types.number

Specifies the amount of time, in milliseconds, to wait after the user input before displaying the dropdown list of autocomplete suggestions. This delay helps control how quickly the suggestions appear, allowing for smoother user experience and reducing unnecessary searches as the user types.

Default value

100

Examples

Markup and runtime examples for autoCompleteDelay:

HTML:

<smart-combo-box auto-complete-delay="250"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.autoCompleteDelay = 500;

Read the current value:

const el = document.querySelector('smart-combo-box');
const autoCompleteDelay = el.autoCompleteDelay;

autoOpenShortcutKeyEnables users to specify one or more custom key names that will trigger the opening of the popup when pressed. This allows for flexible keyboard shortcuts tailored to user preferences or application requirements. string[]

Enables users to specify one or more custom key names that will trigger the opening of the popup when pressed. This allows for flexible keyboard shortcuts tailored to user preferences or application requirements.

Examples

Markup and runtime examples for autoOpenShortcutKey:

HTML:

<smart-combo-box auto-open-shortcut-key="["ArrowUp", "ArrowDown"]"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.autoOpenShortcutKey = ["ArrowDown"];

Read the current value:

const el = document.querySelector('smart-combo-box');
const autoOpenShortcutKey = el.autoOpenShortcutKey;

dataSourceSpecifies the source of data to populate the ComboBox. The dataSource can be provided in several formats:- An array of strings or numbers, where each item becomes a selectable option in the ComboBox.- An array of objects, where each object represents a list item and its properties define the displayed information and associated value (e.g., label for display text, value for the underlying value, and optionally group to categorize items).- A callback function that returns an array of items in either of the above formats, enabling dynamic or asynchronous data loading.This flexible dataSource configuration allows the ComboBox to support simple lists, categorized lists, or dynamically retrieved data.any

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

- An array of strings or numbers, where each item becomes a selectable option in the ComboBox.
- An array of objects, where each object represents a list item and its properties define the displayed information and associated value (e.g., label for display text, value for the underlying value, and optionally group to categorize items).
- A callback function that returns an array of items in either of the above formats, enabling dynamic or asynchronous data loading.

This flexible dataSource configuration allows the ComboBox to support simple lists, categorized lists, or dynamically retrieved data.

Try a demo showcasing the dataSource property.

Examples

Markup and runtime examples for dataSource:

HTML:

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

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

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

Read the current value:

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

disabledControls whether the combo box is active or inactive. When enabled, users can interact with the combo box to select or enter a value. When disabled, the combo box is non-interactive and appears grayed out, preventing any user input or selection.boolean

Controls whether the combo box is active or inactive. When enabled, users can interact with the combo box to select or enter a value. When disabled, the combo box is non-interactive and appears grayed out, preventing any user input or selection.

Default value

false
Try a demo showcasing the disabled property.

Examples

Markup and runtime examples for disabled:

HTML attribute:

<smart-combo-box disabled></smart-combo-box>

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

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

Read the current value:

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

displayLoadingIndicatorSpecifies whether a visual indicator (such as a loading spinner or progress bar) will be displayed while filtering data locally or when retrieving items from a remote source. This helps inform users that a filtering operation or data fetch is in progress.boolean

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

Default value

false
Try a demo showcasing the displayLoadingIndicator property.

Examples

Markup and runtime examples for displayLoadingIndicator:

HTML attribute:

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

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

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

Read the current value:

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

displayMemberSets or retrieves the displayMember property. The displayMember property defines the specific field name within each data object in the collection provided by the 'dataSource' property. This field's value is used for displaying items in the UI component, allowing you to control which attribute of your data objects is shown to the user.string

Sets or retrieves the displayMember property. The displayMember property defines the specific field name within each data object in the collection provided by the 'dataSource' property. This field's value is used for displaying items in the UI component, allowing you to control which attribute of your data objects is shown to the user.

Default value

""""

Examples

Markup and runtime examples for displayMember:

HTML:

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

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

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

Read the current value:

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

dropDownAppendToSpecifies the parent container for the dropdown element. The dropDownAppendTo property accepts a CSS selector string, an element's ID, the string value 'body', or a direct reference to an HTML element. By default, the dropdown is appended to its original parent in the DOM. However, if one of the containing elements has CSS properties (such as overflow: hidden) that restrict the dropdown's visibility, you can set this property—commonly to 'body'—to append the dropdown directly to the <body> element and ensure it displays properly.Possible values:- A CSS selector string (e.g., '.container' or '#mainDiv')- The string 'body'- A direct reference to an existing HTML element- An element's ID (as a string)- null (to reset and move the dropdown back to its original parent)This property improves compatibility in layouts with restricted overflow by allowing the dropdown to be rendered in a container of your choosing. Resetting dropDownAppendTo to null restores the dropdown to its initial placement within the DOM.string

Specifies the parent container for the dropdown element. The dropDownAppendTo property accepts a CSS selector string, an element's ID, the string value 'body', or a direct reference to an HTML element. By default, the dropdown is appended to its original parent in the DOM. However, if one of the containing elements has CSS properties (such as overflow: hidden) that restrict the dropdown's visibility, you can set this property—commonly to 'body'—to append the dropdown directly to the <body> element and ensure it displays properly.

Possible values:
- A CSS selector string (e.g., '.container' or '#mainDiv')
- The string 'body'
- A direct reference to an existing HTML element
- An element's ID (as a string)
- null (to reset and move the dropdown back to its original parent)

This property improves compatibility in layouts with restricted overflow by allowing the dropdown to be rendered in a container of your choosing. Resetting dropDownAppendTo to null restores the dropdown to its initial placement within the DOM.

Default value

"null"
Try a demo showcasing the dropDownAppendTo property.

Examples

Markup and runtime examples for dropDownAppendTo:

HTML:

<smart-combo-box drop-down-append-to="body"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownAppendTo = null;

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownAppendTo = el.dropDownAppendTo;

dropDownButtonPositionSpecifies the location of the dropdown button relative to its associated input field or container. Possible positions may include "left," "right," "top," or "bottom," allowing developers to control where the dropdown button appears in the user interface."left" | "right" | "top" | "bottom"

Specifies the location of the dropdown button relative to its associated input field or container. Possible positions may include "left," "right," "top," or "bottom," allowing developers to control where the dropdown button appears in the user interface.

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.

Examples

Markup and runtime examples for dropDownButtonPosition:

HTML:

<smart-combo-box drop-down-button-position="left"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownButtonPosition = "right";

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownButtonPosition = el.dropDownButtonPosition;

dropDownHeightSpecifies the height of the dropdown menu. By default, this property is set to an empty string, which means the dropdown’s height will be determined by the corresponding CSS variable. If a specific value is provided, it will override the CSS variable and set the dropdown height explicitly.string | number

Specifies the height of the dropdown menu. By default, this property is set to an empty string, which means the dropdown’s height will be determined by the corresponding CSS variable. If a specific value is provided, it will override the CSS variable and set the dropdown height explicitly.

Default value

""

Examples

Markup and runtime examples for dropDownHeight:

HTML:

<smart-combo-box drop-down-height="auto"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownHeight = 500;

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownHeight = el.dropDownHeight;

dropDownMaxHeightSpecifies the maximum height of the dropdown menu. By default, this value is set to an empty string, which means the dropdown's max-height will be controlled by a CSS variable instead of an explicit value. If you provide a specific value (e.g., "300px" or "50vh"), it will override the default CSS variable and directly set the maximum height of the dropdown.string | number

Specifies the maximum height of the dropdown menu. By default, this value is set to an empty string, which means the dropdown's max-height will be controlled by a CSS variable instead of an explicit value. If you provide a specific value (e.g., "300px" or "50vh"), it will override the default CSS variable and directly set the maximum height of the dropdown.

Default value

""

Examples

Markup and runtime examples for dropDownMaxHeight:

HTML:

<smart-combo-box drop-down-max-height="800"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownMaxHeight = 1000;

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownMaxHeight = el.dropDownMaxHeight;

dropDownMaxWidthDefines the maximum width of the dropdown menu. By default, this value is set to an empty string, which means the dropdown's maximum width will be determined by a corresponding CSS variable. If a specific value is provided (e.g., "300px" or "50%"), it will override the CSS variable and directly set the maximum width of the dropdown.string | number

Defines the maximum width of the dropdown menu. By default, this value is set to an empty string, which means the dropdown's maximum width will be determined by a corresponding CSS variable. If a specific value is provided (e.g., "300px" or "50%"), it will override the CSS variable and directly set the maximum width of the dropdown.

Default value

""

Examples

Markup and runtime examples for dropDownMaxWidth:

HTML:

<smart-combo-box drop-down-max-width="500"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownMaxWidth = 800;

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownMaxWidth = el.dropDownMaxWidth;

dropDownMinHeightDefines the minimum height of the dropdown component. By default, this property is set to an empty string, which means the dropdown's minimum height is determined by a corresponding CSS variable. If a specific value is provided for this property, it will override the CSS variable and explicitly set the dropdown's minimum height.string | number

Defines the minimum height of the dropdown component. By default, this property is set to an empty string, which means the dropdown's minimum height is determined by a corresponding CSS variable. If a specific value is provided for this property, it will override the CSS variable and explicitly set the dropdown's minimum height.

Default value

""

Examples

Markup and runtime examples for dropDownMinHeight:

HTML:

<smart-combo-box drop-down-min-height="50"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownMinHeight = 150;

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownMinHeight = el.dropDownMinHeight;

dropDownMinWidthSpecifies the minimum width of the dropdown component. By default, this property is set to an empty string (""). When left unset, the dropdown’s minimum width is determined by a CSS variable, allowing for flexible styling through external stylesheets. To override the CSS value, assign a specific width value (e.g., "200px" or "10rem") to this property.string | number

Specifies the minimum width of the dropdown component. By default, this property is set to an empty string (""). When left unset, the dropdown’s minimum width is determined by a CSS variable, allowing for flexible styling through external stylesheets. To override the CSS value, assign a specific width value (e.g., "200px" or "10rem") to this property.

Default value

""

Examples

Markup and runtime examples for dropDownMinWidth:

HTML:

<smart-combo-box drop-down-min-width="100"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownMinWidth = 90;

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownMinWidth = el.dropDownMinWidth;

dropDownOpenModeSpecifies the direction or animation in which the dropdown menu will appear when activated, such as opening upwards, downwards, or with a specific transition effect."none" | "default" | "dropDownButton" | "auto"

Specifies the direction or animation in which the dropdown menu will appear when activated, such as opening upwards, downwards, 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 closes when not.

Default value

"default"
Try a demo showcasing the dropDownOpenMode property.

Examples

Markup and runtime examples for dropDownOpenMode:

HTML:

<smart-combo-box drop-down-open-mode="dropDownButton"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownOpenMode = "auto";

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownOpenMode = el.dropDownOpenMode;

dropDownOverlayIf this property is enabled, opening the element's dropdown will insert a transparent overlay between the dropdown and the rest of the document. This overlay covers the entire viewport except for the dropdown itself, capturing all click events outside the dropdown. As a result, any clicks outside the popup will interact with the overlay instead of other elements on the page, allowing you to reliably detect and handle outside clicks (such as to close the dropdown) without unintentionally triggering other DOM elements.boolean

If this property is enabled, opening the element's dropdown will insert a transparent overlay between the dropdown and the rest of the document. This overlay covers the entire viewport except for the dropdown itself, capturing all click events outside the dropdown. As a result, any clicks outside the popup will interact with the overlay instead of other elements on the page, allowing you to reliably detect and handle outside clicks (such as to close the dropdown) without unintentionally triggering other DOM elements.

Default value

false

Examples

Markup and runtime examples for dropDownOverlay:

HTML attribute:

<smart-combo-box drop-down-overlay></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownOverlay = false;

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownOverlay = el.dropDownOverlay;

dropDownPlaceholderSpecifies the text or content to be shown in the dropdown as a placeholder when the dropdown contains no selectable items. This placeholder provides guidance or context to the user, indicating that there are currently no available options.string

Specifies the text or content to be shown in the dropdown as a placeholder when the dropdown contains no selectable items. This placeholder provides guidance or context to the user, indicating that there are currently no available options.

Default value

"No Items"
Try a demo showcasing the dropDownPlaceholder property.

Examples

Markup and runtime examples for dropDownPlaceholder:

HTML:

<smart-combo-box drop-down-placeholder="No Items"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownPlaceholder = "Empty";

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownPlaceholder = el.dropDownPlaceholder;

dropDownPositionSpecifies the placement of the dropdown menu relative to its trigger element when opened (e.g., above, below, left, or right). This setting controls where the dropdown appears on the screen in relation to the element that activates it."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 (e.g., above, below, left, or right). This setting controls where the dropdown appears on the screen in relation to the element that activates it.

Allowed Values

  • "auto" - The position is automatically determines 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.

Examples

Markup and runtime examples for dropDownPosition:

HTML:

<smart-combo-box drop-down-position="top"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownPosition = "bottom";

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownPosition = el.dropDownPosition;

dropDownWidthSpecifies the width of the dropdown menu. By default, this property is set to an empty string, allowing the dropdown's width to be determined by the associated CSS variable (typically via custom properties or theme settings). If a value is provided, it overrides the CSS variable and directly sets the dropdown's width.string | number

Specifies the width of the dropdown menu. By default, this property is set to an empty string, allowing the dropdown's width to be determined by the associated CSS variable (typically via custom properties or theme settings). If a value is provided, it overrides the CSS variable and directly sets the dropdown's width.

Default value

""

Examples

Markup and runtime examples for dropDownWidth:

HTML:

<smart-combo-box drop-down-width="auto"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.dropDownWidth = 500;

Read the current value:

const el = document.querySelector('smart-combo-box');
const dropDownWidth = el.dropDownWidth;

escKeyModeSpecifies how the element should respond when the Escape key is pressed by the user. This property allows you to define actions such as closing a modal, dismissing a dialog, or triggering a custom event when the Escape key is detected while the element is focused or active."none" | "previousValue" | "clearValue"

Specifies how the element should respond when the Escape key is pressed by the user. This property allows you to define actions such as closing a modal, dismissing a dialog, or triggering a custom event when the Escape key is detected while the element is focused or active.

Allowed Values

  • "none" - Nothing happens on escape key.
  • "previousValue" - The previous value is displayed.
  • "clearValue" - The value is cleared.

Default value

"null"

Examples

Markup and runtime examples for escKeyMode:

HTML:

<smart-combo-box esc-key-mode="contains"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.escKeyMode = "equals";

Read the current value:

const el = document.querySelector('smart-combo-box');
const escKeyMode = el.escKeyMode;

filterableSpecifies whether the filtering feature is active. When set to true, users can apply filters to narrow down displayed data; when false, filtering options are disabled and all data is shown without restriction.boolean

Specifies whether the filtering feature is active. When set to true, users can apply filters to narrow down displayed data; when false, filtering options are disabled and all data is shown without restriction.

Default value

false
Try a demo showcasing the filterable property.

Examples

Markup and runtime examples for filterable:

HTML attribute:

<smart-combo-box filterable></smart-combo-box>

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

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

Read the current value:

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

filterInputPlaceholderSpecifies the placeholder text displayed inside the dropdown list’s filter input field, guiding users on what to enter when searching or filtering options.string

Specifies the placeholder text displayed inside the dropdown list’s filter input field, guiding users on what to enter when searching or filtering options.

Default value

""
Try a demo showcasing the filterInputPlaceholder property.

Examples

Markup and runtime examples for filterInputPlaceholder:

HTML:

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

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

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

Read the current value:

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

filterModeSpecifies the filtering behavior for the Combo Box, controlling how user input is matched against the available options (e.g., contains, starts with, or exact match). This property determines which options are displayed in the dropdown list as the user types."contains" | "containsIgnoreCase" | "custom" | "doesNotContain" | "doesNotContainIgnoreCase" | "equals" | "equalsIgnoreCase" | "startsWith" | "startsWithIgnoreCase" | "endsWith" | "endsWithIgnoreCase"

Specifies the filtering behavior for the Combo Box, controlling how user input is matched against the available options (e.g., contains, starts with, or exact match). This property determines which options are displayed in the dropdown list as the user types.

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"
Try a demo showcasing the filterMode property.

Examples

Markup and runtime examples for filterMode:

HTML:

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

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

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

Read the current value:

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

groupedWhen enabled, this option automatically groups the items based on the first letter of each item's value or label. Note: This grouping feature is only available if the dataSource does not already include predefined groups. If the dataSource is already grouped, this setting will have no effect.boolean

When enabled, this option automatically groups the items based on the first letter of each item's value or label. Note: This grouping feature is only available if the dataSource does not already include predefined groups. If the dataSource is already grouped, this setting will have no effect.

Default value

false

Examples

Markup and runtime examples for grouped:

HTML attribute:

<smart-combo-box grouped></smart-combo-box>

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

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

Read the current value:

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

groupMemberSpecifies which attribute of the dataSource object should be used to group items in the ListBox. By default, if this property (groupMember) is not set, the ListBox will use the 'group' property from each dataSource item to organize groups. This property is particularly useful when loading data from a JSON file, allowing you to designate a specific property from your data objects to determine the grouping of items—especially if your JSON structure uses a different property name for grouping.string

Specifies which attribute of the dataSource object should be used to group items in the ListBox. By default, if this property (groupMember) is not set, the ListBox will use the 'group' property from each dataSource item to organize groups. This property is particularly useful when loading data from a JSON file, allowing you to designate a specific property from your data objects to determine the grouping of items—especially if your JSON structure uses a different property name for grouping.

Default value

""

Examples

Markup and runtime examples for groupMember:

HTML:

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

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

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

Read the current value:

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

hintDisplays supplementary helper text beneath the element. This hint is visible exclusively when the element is in focus, providing contextual guidance to users as they interact with the field.string

Displays supplementary helper text beneath the element. This hint is visible exclusively when the element is in focus, providing contextual guidance to users as they interact with the field.

Default value

""

Examples

Markup and runtime examples for hint:

HTML:

<smart-combo-box hint="Helper text"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.hint = "Hint";

Read the current value:

const el = document.querySelector('smart-combo-box');
const hint = el.hint;

horizontalScrollBarVisibilityControls whether the horizontal scroll bar is displayed within the dropdown menu when the content exceeds the available width."auto" | "disabled" | "hidden" | "visible"

Controls whether the horizontal scroll bar is displayed within the dropdown menu when the content exceeds the available width.

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-combo-box horizontal-scroll-bar-visibility="disabled"></smart-combo-box>

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

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

Read the current value:

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

incrementalSearchDelayThe 'IncrementalSearchDelay' property defines the duration, in milliseconds, to wait after the user stops typing before clearing the previous search query. This timer begins as soon as the user finishes typing. During this delay period, no new search query will be initiated. Only after the specified delay has elapsed will the current search input be cleared, allowing a new search query to be started. This helps to optimize performance and user experience by preventing unnecessary or premature queries while the user is still entering their search terms.number

The 'IncrementalSearchDelay' property defines the duration, in milliseconds, to wait after the user stops typing before clearing the previous search query. This timer begins as soon as the user finishes typing. During this delay period, no new search query will be initiated. Only after the specified delay has elapsed will the current search input be cleared, allowing a new search query to be started. This helps to optimize performance and user experience by preventing unnecessary or premature queries while the user is still entering their search terms.

Default value

700

Examples

Markup and runtime examples for incrementalSearchDelay:

HTML:

<smart-combo-box incremental-search-delay="100"></smart-combo-box>

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

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

Read the current value:

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

incrementalSearchModeConfigures or retrieves the current mode of incremental search. By default, incremental search is enabled, allowing users to type while the dropdown is focused to quickly filter and highlight matching options. Modifying this setting controls how user input is processed for searching within the dropdown list."contains" | "containsIgnoreCase" | "doesNotContain" | "doesNotContainIgnoreCase" | "equals" | "equalsIgnoreCase" | "startsWith" | "startsWithIgnoreCase" | "endsWith" | "endsWithIgnoreCase"

Configures or retrieves the current mode of incremental search. By default, incremental search is enabled, allowing users to type while the dropdown is focused to quickly filter and highlight matching options. Modifying this setting controls how user input is processed for searching within the dropdown 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-combo-box incremental-search-mode="contains"></smart-combo-box>

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

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

Read the current value:

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

inputMemberRepresents the property name of a List item whose value will be displayed in the input field when a ListItem is selected. This allows developers to control which property of each item is shown in the input, such as displaying the item's value instead of its label. By default, the label property is used for display. This option is useful when you want to customize the displayed content, for example, to show a unique identifier or value rather than the descriptive label.string

Represents the property name of a List item whose value will be displayed in the input field when a ListItem is selected. This allows developers to control which property of each item is shown in the input, such as displaying the item's value instead of its label. By default, the label property is used for display. This option is useful when you want to customize the displayed content, for example, to show a unique identifier or value rather than the descriptive label.

Default value

""
Try a demo showcasing the inputMember property.

Examples

Markup and runtime examples for inputMember:

HTML:

<smart-combo-box input-member="label"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.inputMember = "value";

Read the current value:

const el = document.querySelector('smart-combo-box');
const inputMember = el.inputMember;

inputPurposeSpecifies the expected type of information for the input field and informs the browser about the nature of the data to be entered. This guidance allows user agents (such as browsers and password managers) to determine if they can provide automated assistance—like autofilling relevant values—when the element is used in a form. The value assigned to this property directly maps to the standard HTML autocomplete attribute. Common values include 'on' (enable autocomplete), 'off' (disable autocomplete), 'name' (full name), 'organization' (company or organization), 'email', 'street-address', and many others, as specified by the HTML standard. Using an appropriate value improves user experience, enhances accessibility, and helps maintain privacy and security standards within web forms.string

Specifies the expected type of information for the input field and informs the browser about the nature of the data to be entered. This guidance allows user agents (such as browsers and password managers) to determine if they can provide automated assistance—like autofilling relevant values—when the element is used in a form. The value assigned to this property directly maps to the standard HTML autocomplete attribute. Common values include 'on' (enable autocomplete), 'off' (disable autocomplete), 'name' (full name), 'organization' (company or organization), 'email', 'street-address', and many others, as specified by the HTML standard. Using an appropriate value improves user experience, enhances accessibility, and helps maintain privacy and security standards within web forms.

Default value

"off"

Examples

Markup and runtime examples for inputPurpose:

HTML:

<smart-combo-box input-purpose="on"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.inputPurpose = "country";

Read the current value:

const el = document.querySelector('smart-combo-box');
const inputPurpose = el.inputPurpose;

itemHeightSpecifies the height (in pixels) for each list item when rendering the list. This property is only applicable when list virtualization is enabled, as it helps optimize rendering performance by allowing the component to calculate and render only the visible items.number

Specifies the height (in pixels) for each list item when rendering the list. This property is only applicable when list virtualization is enabled, as it helps optimize rendering performance by allowing the component to calculate and render only the visible items.

Examples

Markup and runtime examples for itemHeight:

HTML:

<smart-combo-box item-height="20"></smart-combo-box>

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

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

Read the current value:

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

itemMeasureModeSpecifies the algorithm used to calculate the width of each item. This setting determines how the width of an item is measured, such as using the item's intrinsic content size, a fixed value, or a percentage of the container. Adjust this parameter to control how item widths are determined within the layout."auto" | "precise"

Specifies the algorithm used to calculate the width of each item. This setting determines how the width of an item is measured, such as using the item's intrinsic content size, a fixed value, or a percentage of the container. Adjust this parameter to control how item widths are determined within the layout.

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-combo-box item-measure-mode="precise"></smart-combo-box>

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

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

Read the current value:

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

itemsA getter method that retrieves and returns an array containing all list ('li') elements currently present within the dropdown menu. This allows you to easily access and manipulate every item displayed in the dropdown.{label: string, value: string}[]

A getter method that retrieves and returns an array containing all list ('li') elements currently present within the dropdown menu. This allows you to easily access and manipulate every item displayed in the dropdown.

Default value

""

itemTemplateThe itemTemplate property is a string that specifies the ID of an HTMLTemplateElement present in the DOM. This template is used to define and customize the structure and content of individual list items, allowing developers to control how each item appears when rendered in the list.any

The itemTemplate property is a string that specifies the ID of an HTMLTemplateElement present in the DOM. This template is used to define and customize the structure and content of individual list items, allowing developers to control how each item appears when rendered in the list.

Try a demo showcasing the itemTemplate property.

Examples

Markup and runtime examples for itemTemplate:

HTML:

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

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

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

Read the current value:

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

labelDisplays a small text label positioned above the element, typically used to provide context, instructions, or additional information to users.string

Displays a small text label positioned above the element, typically used to provide context, instructions, or additional information to users.

Default value

""
Try a demo showcasing the label property.

Examples

Markup and runtime examples for label:

HTML:

<smart-combo-box label="Helper text"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.label = "Label";

Read the current value:

const el = document.querySelector('smart-combo-box');
const label = el.label;

loadingIndicatorPlaceholderSpecifies the text that appears alongside the loading indicator when the loader is visible and positioned at the top or bottom of the component. This text provides users with contextual information or status updates during loading.string

Specifies the text that appears alongside the loading indicator when the loader is visible and positioned at the top or bottom of the component. This text provides users with contextual information or status updates during loading.

Default value

"Loading..."

Examples

Markup and runtime examples for loadingIndicatorPlaceholder:

HTML:

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

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

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

Read the current value:

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

loadingIndicatorPositionSpecifies the exact location on the user interface where the loading indicator will be displayed, such as at the top, center, or bottom of the screen or component."bottom" | "center" | "top"

Specifies the exact location on the user interface where the loading indicator will be displayed, such as at the top, center, or bottom of the screen or component.

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"

Examples

Markup and runtime examples for loadingIndicatorPosition:

HTML:

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

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

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

Read the current value:

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

localeSpecifies or retrieves the current language setting for the component. This property determines which language is used when displaying content from the messages property, allowing for localization and internationalization of displayed messages. Set this property to a supported language code (e.g., "en", "fr") to load the corresponding translations from the messages object.string

Specifies or retrieves the current language setting for the component. This property determines which language is used when displaying content from the messages property, allowing for localization and internationalization of displayed messages. Set this property to a supported language code (e.g., "en", "fr") to load the corresponding translations from the messages object.

Default value

"en"

Examples

Markup and runtime examples for locale:

HTML:

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

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

const el = document.querySelector('smart-combo-box');
el.locale = "en";

Read the current value:

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

localizeFormatFunctionA callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this callback to modify message text, apply dynamic values, or implement custom formatting logic before the localized messages are delivered to your application.function | null

A callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this callback to modify message text, apply dynamic values, or implement custom formatting logic before the localized messages are delivered to your application.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

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

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

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

Read the current value:

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

maxLengthSpecifies the maximum number of characters that can be entered into the input field. Any additional characters beyond this limit will not be accepted. This helps enforce data validation and consistency for user input.number

Specifies the maximum number of characters that can be entered into the input field. Any additional characters beyond this limit will not be accepted. This helps enforce data validation and consistency for user input.

Default value

-1

Examples

Markup and runtime examples for maxLength:

HTML:

<smart-combo-box max-length="3"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.maxLength = 4;

Read the current value:

const el = document.querySelector('smart-combo-box');
const maxLength = el.maxLength;

messagesSpecifies or retrieves an object containing localized string values used within the widget’s user interface. This property enables the customization and translation of UI text for different languages or regions. It is intended to be used together with the locale property, allowing you to easily provide or update localized strings according to the selected locale.object

Specifies or retrieves an object containing localized string values used within the widget’s user interface. This property enables the customization and translation of UI text for different languages or regions. It is intended to be used together with the locale property, allowing you to easily provide or update localized strings according to the selected locale.

Default value




"en": {

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

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

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

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

"moduleUndefined": "Module is undefined.",

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

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

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

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

}

Try a demo showcasing the messages property.

Examples

Markup and runtime examples for messages:

HTML:

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

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

const el = document.querySelector('smart-combo-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.","invalidNode":"{{elementType}}: Invalid parameter '{{node}}' when calling {{method}}."}};

Read the current value:

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

minLengthSpecifies the minimum number of characters a user must enter in the input field before the autocomplete feature is activated and suggestions are displayed.number

Specifies the minimum number of characters a user must enter in the input field before the autocomplete feature is activated and suggestions are displayed.

Default value

2
Try a demo showcasing the minLength property.

Examples

Markup and runtime examples for minLength:

HTML:

<smart-combo-box min-length="3"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.minLength = 4;

Read the current value:

const el = document.querySelector('smart-combo-box');
const minLength = el.minLength;

nameSets or retrieves the value of the element's name attribute. The name attribute uniquely identifies form elements when submitting HTML forms, allowing the form data to be organized and accessed by name on the server side. This attribute is essential for grouping form controls and accurately transmitting user input during form submission.string

Sets or retrieves the value of the element's name attribute. The name attribute uniquely identifies form elements when submitting HTML forms, allowing the form data to be organized and accessed by name on the server side. This attribute is essential for grouping form controls and accurately transmitting user input during form submission.

Default value

""

Examples

Markup and runtime examples for name:

HTML:

<smart-combo-box name="combobox"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.name = "comboBox2";

Read the current value:

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

openedSpecifies whether the popup is currently visible (open) or hidden (closed) in the user interface.boolean

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

Default value

false

Examples

Markup and runtime examples for opened:

HTML attribute:

<smart-combo-box opened></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.opened = false;

Read the current value:

const el = document.querySelector('smart-combo-box');
const opened = el.opened;

placeholderSpecifies the placeholder text that appears inside the input field when it is empty, providing guidance or example content to the user.string

Specifies the placeholder text that appears inside the input field when it is empty, providing guidance or example content to the user.

Default value

""

Examples

Markup and runtime examples for placeholder:

HTML:

<smart-combo-box placeholder="Choose:"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.placeholder = "Submit";

Read the current value:

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

readonlyPrevents any user interactions with the element, including clicking, tapping, selecting, hovering, or focusing. While this is enabled, the element will not respond to mouse, keyboard, or touch events, effectively making it non-interactive for users.boolean

Prevents any user interactions with the element, including clicking, tapping, selecting, hovering, or focusing. While this is enabled, the element will not respond to mouse, keyboard, or touch events, effectively making it non-interactive for users.

Default value

false
Try a demo showcasing the readonly property.

Examples

Markup and runtime examples for readonly:

HTML attribute:

<smart-combo-box readonly></smart-combo-box>

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

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

Read the current value:

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

resizeIndicatorControls the visibility of the resize indicator located in the bottom-right corner of the dropdown component. When this property is set to true, users will see a handle allowing them to resize the dropdown area. This property should be used together with the resizeMode property to define both the availability and behavior of the resizing feature.boolean

Controls the visibility of the resize indicator located in the bottom-right corner of the dropdown component. When this property is set to true, users will see a handle allowing them to resize the dropdown area. This property should be used together with the resizeMode property to define both the availability and behavior of the resizing feature.

Default value

false

Examples

Markup and runtime examples for resizeIndicator:

HTML attribute:

<smart-combo-box resize-indicator></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.resizeIndicator = false;

Read the current value:

const el = document.querySelector('smart-combo-box');
const resizeIndicator = el.resizeIndicator;

resizeModeSpecifies whether the drop-down menu is resizable by the user. If resizing is enabled, a resize bar will be displayed along the top or bottom edge of the drop-down, allowing users to click and drag to adjust its height. Disabling this option removes the resize bar and prevents any manual resizing of the drop-down component."none" | "horizontal" | "vertical" | "both"

Specifies whether the drop-down menu is resizable by the user. If resizing is enabled, a resize bar will be displayed along the top or bottom edge of the drop-down, allowing users to click and drag to adjust its height. Disabling this option removes the resize bar and prevents any manual resizing of the drop-down component.

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

"null"
Try a demo showcasing the resizeMode property.

Examples

Markup and runtime examples for resizeMode:

HTML:

<smart-combo-box resize-mode="horizontal"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.resizeMode = "vertical";

Read the current value:

const el = document.querySelector('smart-combo-box');
const resizeMode = el.resizeMode;

rightToLeftSpecifies or retrieves a value that determines whether the element’s text direction is set to support right-to-left (RTL) languages, such as Arabic or Hebrew. When enabled, the element and its content are aligned according to RTL formatting, ensuring proper display for locales that use right-to-left scripts.boolean

Specifies or retrieves a value that determines whether the element’s text direction is set to support right-to-left (RTL) languages, such as Arabic or Hebrew. When enabled, the element and its content are aligned according to RTL formatting, ensuring proper display for locales that use right-to-left scripts.

Default value

false
Try a demo showcasing the rightToLeft property.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

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

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

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

Read the current value:

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

selectedIndexesSets or retrieves the selected indexes. The selected indexes property is an array containing the numeric indexes of the items that are currently selected. Each value in the array corresponds to the position of a selected item within the overall list or collection. Assigning a new array to this property updates the selection state to match the specified indexes; retrieving it returns the current selection as an array of indexes. number[]

Sets or retrieves the selected indexes. The selected indexes property is an array containing the numeric indexes of the items that are currently selected. Each value in the array corresponds to the position of a selected item within the overall list or collection. Assigning a new array to this property updates the selection state to match the specified indexes; retrieving it returns the current selection as an array of indexes.

Try a demo showcasing the selectedIndexes property.

Examples

Markup and runtime examples for selectedIndexes:

HTML:

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

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

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

Read the current value:

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

selectedValues "Sets or retrieves the currently selected indexes. The 'selected' property holds an array of the indices corresponding to the items that are marked as selected. When setting this property, provide an array of indexes to specify which items should be selected. When getting this property, it returns the array of indexes for the currently selected items." string[]


"Sets or retrieves the currently selected indexes. The 'selected' property holds an array of the indices corresponding to the items that are marked as selected. When setting this property, provide an array of indexes to specify which items should be selected. When getting this property, it returns the array of indexes for the currently selected items."

Try a demo showcasing the selectedValues property.

Examples

Markup and runtime examples for selectedValues:

HTML:

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

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

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

Read the current value:

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

selectionDisplayModeSpecifies the content or value that will appear within the input field, either as a default value, user-entered data, or dynamically generated content. This setting controls what the user sees and interacts with inside the input element."plain" | "placeholder" | "tokens"

Specifies the content or value that will appear within the input field, either as a default value, user-entered data, or dynamically generated content. This setting controls what the user sees and interacts with inside the input element.

Allowed Values

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

Default value

"plain"
Try a demo showcasing the selectionDisplayMode property.

Examples

Markup and runtime examples for selectionDisplayMode:

HTML:

<smart-combo-box selection-display-mode="placeholder"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.selectionDisplayMode = "default";

Read the current value:

const el = document.querySelector('smart-combo-box');
const selectionDisplayMode = el.selectionDisplayMode;

selectionModeSpecifies the maximum number of items that a user is allowed to select at one time. If this value is set to 1, only single selection is permitted; higher values allow multiple selections up to the defined limit."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 this value is set to 1, only single selection is permitted; higher values allow multiple selections up to the defined limit.

Allowed Values

  • "none" - Item selection is not allowed.
  • "oneOrManyExtended" - Only one item can be selected unless 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"
Try a demo showcasing the selectionMode property.

Examples

Markup and runtime examples for selectionMode:

HTML:

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

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

const el = document.querySelector('smart-combo-box');
el.selectionMode = "oneOrMany";

Read the current value:

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

sortDirectionSpecifies the sorting order for data, allowing you to choose between ascending ("asc") for lowest-to-highest or alphabetical A–Z sorting, and descending ("desc") for highest-to-lowest or Z–A sorting.string

Specifies the sorting order for data, allowing you to choose between ascending ("asc") for lowest-to-highest or alphabetical A–Z sorting, and descending ("desc") for highest-to-lowest or Z–A sorting.

Default value

"asc"

Examples

Markup and runtime examples for sortDirection:

HTML:

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

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

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

Read the current value:

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

sortedSpecifies whether the items are arranged in alphabetical order. If set to true, the items will be sorted alphabetically; if false, the original order will be preserved.boolean

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

Default value

false

Examples

Markup and runtime examples for sorted:

HTML attribute:

<smart-combo-box sorted></smart-combo-box>

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

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

Read the current value:

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

themeSpecifies the visual theme to be applied to the element. The selected theme controls the element’s appearance, including colors, fonts, and other stylistic properties, ensuring a consistent look and feel across the user interface.string

Specifies the visual theme to be applied to the element. The selected theme controls the element’s appearance, including colors, fonts, and other stylistic properties, ensuring a consistent look and feel across the user interface.

Default value

""
Try a demo showcasing the theme property.

Examples

Markup and runtime examples for theme:

HTML:

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

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

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

Read the current value:

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

tokenTemplateDefines the custom content to display within each token when the selectionDisplayMode is set to "tokens". Tokens visually represent selected items in a multi-select interface and are only applicable when multiple selection is enabled. Use this option to customize how each token appears, such as displaying specific text, icons, or additional data for each selected item.any

Defines the custom content to display within each token when the selectionDisplayMode is set to "tokens". Tokens visually represent selected items in a multi-select interface and are only applicable when multiple selection is enabled. Use this option to customize how each token appears, such as displaying specific text, icons, or additional data for each selected item.

Try a demo showcasing the tokenTemplate property.

Examples

Markup and runtime examples for tokenTemplate:

HTML:

<smart-combo-box token-template="tokenTemplate"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.tokenTemplate = null;

Read the current value:

const el = document.querySelector('smart-combo-box');
const tokenTemplate = el.tokenTemplate;

unfocusableIf set to true, the element will not be able to receive keyboard or mouse focus, making it inaccessible via tab navigation or programmatic focus methods.boolean

If set to true, the element will not be able to receive keyboard or mouse focus, making it inaccessible via tab navigation or programmatic focus methods.

Default value

false

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

<smart-combo-box unfocusable></smart-combo-box>

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

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

Read the current value:

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

unlockKeySets or retrieves the unlockKey, a unique value required to grant access to the product’s premium features or activate its full functionality.string

Sets or retrieves the unlockKey, a unique value required to grant access to the product’s premium features or activate its full functionality.

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

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

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

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

Read the current value:

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

valueProvides functionality to retrieve (get) or assign (set) the current value of the property. When used as a getter, it returns the property's current value. When used as a setter, it updates the property with the specified value.string

Provides functionality to retrieve (get) or assign (set) the current value of the property. When used as a getter, it returns the property's current value. When used as a setter, it updates the property with the specified value.

Default value

""
Try a demo showcasing the value property.

Examples

Markup and runtime examples for value:

HTML:

<smart-combo-box value="val1"></smart-combo-box>

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

const el = document.querySelector('smart-combo-box');
el.value = "val2";

Read the current value:

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

valueMemberSpecifies which property of each item object should be used as the value for that item. The value designated by valueMember will be stored in the item's value field. This property functions similarly to groupMember, but is focused on identifying the value rather than the group. valueMember is particularly useful when populating a ListBox from a JSON data source, as it allows you to specify which property of your data objects should serve as the unique value for each item in the ListBox.string

Specifies which property of each item object should be used as the value for that item. The value designated by valueMember will be stored in the item's value field. This property functions similarly to groupMember, but is focused on identifying the value rather than the group. valueMember is particularly useful when populating a ListBox from a JSON data source, as it allows you to specify which property of your data objects should serve as the unique value for each item in the ListBox.

Default value

""""

Examples

Markup and runtime examples for valueMember:

HTML:

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

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

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

Read the current value:

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

verticalScrollBarVisibilityControls whether the vertical scroll bar is displayed within the content area, allowing users to scroll vertically when the content extends beyond the visible region."auto" | "disabled" | "hidden" | "visible"

Controls whether the vertical scroll bar is displayed within the content area, allowing users to scroll vertically when the content extends beyond the visible region.

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-combo-box vertical-scroll-bar-visibility="hidden"></smart-combo-box>

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

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

Read the current value:

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

virtualizedDetermines whether virtualization is enabled for the ComboBox. When virtualization is enabled, the ComboBox can efficiently display a very large number of items—such as a million—by only rendering the visible items in the ListBox and dynamically loading items as needed. This significantly improves performance and reduces memory usage, especially with large data sets.boolean

Determines whether virtualization is enabled for the ComboBox. When virtualization is enabled, the ComboBox can efficiently display a very large number of items—such as a million—by only rendering the visible items in the ListBox and dynamically loading items as needed. This significantly improves performance and reduces memory usage, especially with large data sets.

Default value

false

Examples

Markup and runtime examples for virtualized:

HTML attribute:

<smart-combo-box virtualized></smart-combo-box>

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

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

Read the current value:

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

Events

changeThis event is triggered whenever the user changes the current selection, such as highlighting different text or selecting a new item in a list. It allows you to detect and respond to updates in the selected content or options within the interface.CustomEvent

This event is triggered whenever the user changes the current selection, such as highlighting different text or selecting a new item in a list. It allows you to detect and respond to updates in the selected content or options within the interface.

  • 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-combo-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.
})

closeThis event is triggered when the drop-down list is closed, either by the user selecting an option or by clicking outside the menu. It occurs after the drop-down menu is no longer visible, allowing you to perform actions in response to the menu's closure.CustomEvent

This event is triggered when the drop-down list is closed, either by the user selecting an option or by clicking outside the menu. It occurs after the drop-down menu is no longer visible, allowing you to perform actions in response to the menu's closure.

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

Try a demo showcasing the close event.

Examples

Listen for close 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-combo-box')?.addEventListener('close', (event) => {
	// event handling code goes here.
})

closingThis event is triggered right before the dropdown list is about to close, providing an opportunity to intervene. By calling event.preventDefault() within the event handler, you can cancel the closing operation, allowing you to perform validation, display a confirmation dialog, or execute custom logic before the dropdown is closed.CustomEvent

This event is triggered right before the dropdown list is about to close, providing an opportunity to intervene. By calling event.preventDefault() within the event handler, you can cancel the closing operation, allowing you to perform validation, display a confirmation dialog, or execute custom logic before the dropdown is closed.

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

Examples

Listen for closing 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-combo-box')?.addEventListener('closing', (event) => {
	// event handling code goes here.
})

itemClickThis event is triggered whenever a user clicks on a specific item, allowing you to execute custom actions in response to the user's selection. The event provides context about the clicked item, enabling you to access its properties or perform related updates within your application.CustomEvent

This event is triggered whenever a user clicks on a specific item, allowing you to execute custom actions in response to the user's selection. The event provides context about the clicked item, enabling you to access its properties or perform related updates within your application.

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

Try a demo showcasing the itemClick event.

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-combo-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.
})

openThis event is triggered whenever the dropdown list becomes visible to the user, such as when the user clicks or interacts with the control to expand and display the list of available options. Use this event to execute custom logic when the dropdown menu is opened.CustomEvent

This event is triggered whenever the dropdown list becomes visible to the user, such as when the user clicks or interacts with the control to expand and display the list of available options. Use this event to execute custom logic when the dropdown menu is opened.

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

Examples

Listen for open 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-combo-box')?.addEventListener('open', (event) => {
	// event handling code goes here.
})

openingThis event is triggered immediately before the dropdown list is displayed to the user. Within the event handler, you can prevent the dropdown from opening by calling event.preventDefault(). This allows you to implement custom logic to conditionally allow or block the opening of the dropdown, such as validating conditions or managing user permissions before the list is shown.CustomEvent

This event is triggered immediately before the dropdown list is displayed to the user. Within the event handler, you can prevent the dropdown from opening by calling event.preventDefault(). This allows you to implement custom logic to conditionally allow or block the opening of the dropdown, such as validating conditions or managing user permissions before the list is shown.

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

Examples

Listen for opening 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-combo-box')?.addEventListener('opening', (event) => {
	// event handling code goes here.
})

resizeEndThis event is triggered after the user has completed resizing the dropdown menu, signaling that the resizing action has ended and the new dimensions have been set.CustomEvent

This event is triggered after the user has completed resizing the dropdown menu, signaling that the resizing action has ended and the new dimensions have been set.

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

Examples

Listen for resizeEnd 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-combo-box')?.addEventListener('resizeEnd', (event) => {
    const detail = event.detail,
        position = detail.position;

	// event handling code goes here.
})

resizeStartThis event is triggered when the user initiates the resizing action on the dropdown component, such as clicking and dragging a resize handle. It allows developers to detect the exact moment when a resize operation on the dropdown begins.CustomEvent

This event is triggered when the user initiates the resizing action on the dropdown component, such as clicking and dragging a resize handle. It allows developers to detect the exact moment when a resize operation on the dropdown begins.

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

Examples

Listen for resizeStart 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-combo-box')?.addEventListener('resizeStart', (event) => {
    const detail = event.detail,
        position = detail.position;

	// event handling code goes here.
})

scrollBottomReachedThis 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 detect when additional data should be loaded or when no further options remain in the dropdown.CustomEvent

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 detect when additional data should be loaded or when no further options remain in the dropdown.

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

Try a demo showcasing the scrollBottomReached event.

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-combo-box')?.addEventListener('scrollBottomReached', (event) => {
	// event handling code goes here.
})

scrollTopReachedThis event is triggered when the user scrolls to the very beginning (top) of the dropdown list, indicating that no more items are available above the current view.CustomEvent

This event is triggered when the user scrolls to the very beginning (top) of the dropdown list, indicating that no more items are available above the current view.

  • 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-combo-box')?.addEventListener('scrollTopReached', (event) => {
	// event handling code goes here.
})

tokenClickThis event is triggered when a token item (also known as a 'pill') is clicked by the user. By handling this event, developers have the opportunity to intercept the default action that would normally occur when the token is clicked—such as opening a dropdown or performing another related operation. To prevent the default behavior from executing, call event.preventDefault() within your event handler function."CustomEvent

This event is triggered when a token item (also known as a 'pill') is clicked by the user. By handling this event, developers have the opportunity to intercept the default action that would normally occur when the token is clicked—such as opening a dropdown or performing another related operation. To prevent the default behavior from executing, call event.preventDefault() within your event handler function."

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

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 tokenClick 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-combo-box')?.addEventListener('tokenClick', (event) => {
	// event handling code goes here.
})

Methods

add( item: any): voidCreates and appends one or more new items to the collection or list.

Creates and appends one or more new items to the collection or list.

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-combobox, if you host multiple widgets):

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

Try a demo showcasing the add method.

appendChild( node: Node): TAppends a new ListItem element to the end of the existing list of items within the specified container element, thereby updating the list to include the newly added item as its last entry.

Arguments

nodeNode

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

ReturnsNode

clearItems(): voidRemoves all existing items from the dropdown list, resulting in an empty list with no selectable options displayed to the user.

Removes all existing items from the dropdown list, resulting in an empty list with no selectable options displayed to the user.

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

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

Try a demo showcasing the clearItems method.

clearSelection(): voidDeselects all currently selected items, ensuring that no items remain selected. This action clears any existing selections and resets the selection state.

Deselects all currently selected items, ensuring that no items remain selected. This action clears any existing selections and resets the selection state.

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

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

Try a demo showcasing the clearSelection method.

close(): voidCloses the currently open drop-down list, hiding all available options from view and returning the component to its collapsed state. This action ensures that the drop-down menu is no longer visible to the user.

Closes the currently open drop-down list, hiding all available options from view and returning the component to its collapsed state. This action ensures that the drop-down menu is no longer visible to the user.

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

document.querySelector('smart-combo-box')?.close();

Try a demo showcasing the close method.

dataBind(): voidInitiates a data binding process, connecting UI components to the underlying data source. This method refreshes the data source, ensuring that any changes made to the data are reflected in the user interface. It can be used to update displayed information after modifying, adding, or deleting data.

Initiates a data binding process, connecting UI components to the underlying data source. This method refreshes the data source, ensuring that any changes made to the data are reflected in the user interface. It can be used to update displayed information after modifying, adding, or deleting data.

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

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

Try a demo showcasing the dataBind method.

ensureVisible( item: HTMLElement | string): voidScrolls the target item into view within its container, automatically adjusting the scroll position as needed to make sure the entire item is fully visible to the user.

Scrolls the target item into view within its container, automatically adjusting the scroll position as needed to make sure the entire item is fully visible to the user.

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-combobox, if you host multiple widgets):

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

getItem( value: string): HTMLElementReturns a specific item instance from the dropDown list, allowing you to access the properties and methods of the selected list item. This can be used to retrieve information about the item, such as its value, label, or index within the dropDown.

Returns a specific item instance from the dropDown list, allowing you to access the properties and methods of the selected list item. This can be used to retrieve information about the item, such as its value, label, or index within the dropDown.

Arguments

valuestring

The value of an item from the drop down list.

ReturnsHTMLElement

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

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

Try a demo showcasing the getItem method.

insert( position: number, item: any): voidInserts a new item into the array at the specified index position, shifting existing elements to the right to accommodate the new item.

Inserts a new item into the array at the specified index position, shifting existing elements to the right to accommodate the new item.

Arguments

positionnumber

The position where the item must be inserted.

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-combobox, if you host multiple widgets):

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

Try a demo showcasing the insert method.

insertBefore( node: Node, referenceNode: Node | null): TInserts a new ListItem element directly before a specified existing ListItem within the list, preserving the order of the remaining items.

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(): voidDisplays and expands the drop-down list, making all available options visible for selection.

Displays and expands the drop-down list, making all available options visible for selection.

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

document.querySelector('smart-combo-box')?.open();

Try a demo showcasing the open method.

removeAt( position: number): voidRemoves the item located at the specified index or position within a collection (such as an array or list). After removal, the collection is updated so that subsequent items shift to fill the gap, ensuring contiguous indexing.

Removes the item located at the specified index or position within a collection (such as an array or list). After removal, the collection is updated so that subsequent items shift to fill the gap, ensuring contiguous indexing.

Arguments

positionnumber

The position of the removed item.

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

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

Try a demo showcasing the removeAt method.

removeChild( node: Node): TRemoves a specified ListItem from the collection of items contained within the given element, updating the list to reflect the deletion.

Arguments

nodeNode

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

ReturnsNode

select( item: string | HTMLElement): voidSelects a specified item from the dropdown list, allowing users to choose one option from the available choices. This action updates the dropdown’s current selection and can trigger any associated event handlers or changes in the application’s state.

Selects a specified item from the dropdown list, allowing users to choose one option from the available choices. This action updates the dropdown’s current selection and can trigger any associated event handlers or changes in the application’s state.

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-combobox, if you host multiple widgets):

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

Try a demo showcasing the select method.

unselect( item: string | HTMLElement): voidDeselects a specified item from the dropdown list, removing its selected state and reverting the dropdown to reflect that the item is no longer chosen by the user.

Deselects a specified item from the dropdown list, removing its selected state and reverting the dropdown to reflect that the item is no longer chosen by the user.

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-combobox, if you host multiple widgets):

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

Try a demo showcasing the unselect method.

update( position: number, value: any): voidUpdates the selected item in the dropDown list with new data or attributes. This action modifies the existing item rather than adding or removing items from the list, ensuring that any changes are reflected immediately in the user interface. Specify the target item and the updated values to complete the operation.

Updates the selected item in the dropDown list with new data or attributes. This action modifies the existing item rather than adding or removing items from the list, ensuring that any changes are reflected immediately in the user interface. Specify the target item and the updated values to complete the operation.

Arguments

positionnumber

The position where the item must be updated.

valueany

The value of the updated item.

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

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

Try a demo showcasing the update method.

CSS Variables

--smart-combo-box-default-widthvar()

Default value

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

smartComboBox default width

--smart-combo-box-default-heightvar()

Default value

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

smartComboBox default height

--smart-combo-box-drop-down-widthvar()

Default value

"auto"

smartComboBox default width

--smart-combo-box-drop-down-heightvar()

Default value

"auto"

smartComboBox default height

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

""