MultiInput JAVASCRIPT UI Component API

MultiInput Javascript API

Class

MultiInput

MultiInput

MultiInput specifies an input field where the user can enter data. Auto-complete options are displayed for easier input. Allows multiple selection. Selected items are added to the input's value.

Selector

smart-multi-input

Properties

AanimationGets or sets the animation mode. When this property is set to 'none', all animations are disabled. Setting it to other supported values enables the corresponding animation effects.
AautoCompleteDelaySpecifies the amount of time, in milliseconds, to wait before displaying the dropdown list of matching results after the user starts typing in the autocomplete field. This delay helps control how quickly suggestions appear, allowing for smoother user experience and reducing unnecessary search operations as the user types.
DdataSourceSpecifies the source of data used to populate the MultiInput component. The 'dataSource' property accepts one of the following:- 'Array of Strings or Numbers:' Each element is rendered as a selectable item in the MultiInput list.- 'Array of Objects:' Each object should contain properties, typically such as 'label' (the display text) and 'value' (the underlying value), to define the characteristics of each list item.- 'Callback Function:' A function that returns an array of items in either of the above formats.This flexible configuration allows you to define static lists, complex data structures, or dynamically load items as needed.
DdisabledSpecifies whether the element is active and interactive (enabled), or inactive and unresponsive to user interactions (disabled). When set to disabled, the element cannot be clicked, selected, or modified by the user.
DdropDownButtonPositionSpecifies the location where the dropdown button will appear relative to its parent element. Possible values typically include options such as 'left', 'right', 'top', or 'bottom', allowing you to control the visual placement of the button within 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 associated CSS variable. If you provide a specific value (e.g., '200px', '20rem'), it will override the default CSS-controlled height and explicitly set the dropdown's height to the specified value.
DdropDownWidthSpecifies the width of the dropdown menu. By default, this property is an empty string ('""'), meaning the dropdown's width is determined by a corresponding CSS variable. You can override this behavior by explicitly setting a value (e.g., '"200px"', '"50%"') to directly control the dropdown's width via inline styles, rather than relying on the CSS variable.
IinputPurposeSpecifies the intended purpose of the input field and indicates to the browser what type of information is expected from the user. This setting guides the browser in offering automated assistance, such as autocomplete suggestions, when the input is used within a form. The value corresponds directly to the standard HTML autocomplete attribute, which helps user agents (such as browsers) determine whether and how to autofill the field. You can assign values such as 'on' (enable autocomplete), 'off' (disable autocomplete), or more specific values like 'name', 'organization', 'street-address', 'email', and others, to optimize the autofill behavior and improve the user experience.
IitemsSpecifies the maximum number of matched items to display in the dropdown list in response to a new autoComplete query. By default, up to 8 items will be shown in the dropdown. If more items match the query, only the first 8 will be visible, ensuring the dropdown remains concise and user-friendly. Adjust this value to control how many results are presented to users at once.
UunlockKeySets or retrieves the 'unlockKey' property, a unique key or code required to unlock access to the product’s features or full functionality. Use this property to provide the necessary unlock key when granting access, or to obtain the currently set unlock key.
LlocaleSpecifies or retrieves the current language setting for the component. This property determines which set of localized messages, defined in the messages property, will be displayed. When you update the language, the component automatically uses the corresponding message set from messages to reflect the selected language.
LlocalizeFormatFunctionCallback function that allows developers to customize the formatting of messages returned by the Localization Module. This function receives the original message and relevant context, enabling dynamic modification—such as value interpolation, date and number formatting, or applying custom transformations—before the finalized message is delivered to the application.
MmessagesDefines or retrieves an object containing the set of text strings used within the widget, allowing these strings to be customized for different languages or regions. This property works together with the locale property to provide localization support, ensuring that UI labels, messages, and other user-facing text can be displayed appropriately based on the selected language.
MminLengthSpecifies the minimum number of characters a user must enter into the input field before the autocomplete functionality is activated. Once this threshold is reached, the dropdown will appear, displaying a list of items that match the user's input.
NnameSets or retrieves the value of the element's "name" attribute. This attribute is used to identify form elements when submitting data through an HTML form. The value assigned to the "name" attribute is sent as the key in the key-value pair for the form data, allowing the server to process the input accordingly.
OopenedIndicates whether the dropdown menu is currently open (true) or closed (false).
PplaceholderSpecifies the placeholder text displayed inside the input field before the user enters a value. This text typically provides a hint or example of the expected input.
QquerySets or retrieves the query string used to filter the list of items. This query is applied during the autoComplete operation to determine which items are shown based on the user's input. If the query is an empty string, all items from the data source are displayed without any filtering.
QqueryModeSpecifies the query mode used for the autocomplete feature. This property defines how user input is matched against available options, determining the matching algorithm (e.g., prefix, infix, or token matching) applied during autocomplete operations. Adjust this setting to control how search suggestions are generated and filtered based on the user's query.
RreadonlyControls whether the user can enter text directly into the input field. When dropDownButtonPosition is set to 'left' or 'right', the readonly property specifies how the element behaves if a dataSource is provided: - If readonly is false, the element functions as a ComboBox, allowing users to either type custom text or select from the list. - If readonly is true, the element acts as a DropDownList, restricting input to selection only from the available list items; custom text entry is not allowed.
RrightToLeftSpecifies or retrieves a value that determines whether the element’s alignment is configured for right-to-left (RTL) text direction, which is commonly used in languages such as Arabic or Hebrew. When enabled, the content within the element will align and flow appropriately to support RTL locales.
SseparatorSpecifies the character or string used to separate multiple selected items within the input field. This delimiter controls how selected values are displayed and parsed, ensuring each item is clearly distinguished in the input.
SselectedValuesRetrieves or assigns an array containing the currently selected values. Each item in the array represents a selected option, allowing for multiple selection handling.
SselectAllSpecifies whether an additional item should be displayed at the top of the options list. This item functions as a "Select All / Deselect All" control, allowing users to quickly select or unselect all available options in the list.
SsortedSpecifies whether the items are arranged in alphabetical order. If set to true, the items will be sorted from A to Z; if set to false, the items will retain their original, unsorted order.
SsortDirectionSpecifies the sorting order used when sort is enabled. Accepts either asc for ascending order or desc for descending order.
TthemeSpecifies the visual theme applied to the element. The selected theme controls the element’s overall appearance, including colors, fonts, and styling, ensuring a consistent look and feel across the user interface.
TtypeSpecifies the type of input allowed in the field. The input type controls the kind of data the user can enter (such as text, email, number, password, etc.), which helps ensure data is entered in the correct format and may trigger specialized keyboards or validation behaviors on supported devices.
UunfocusableWhen set to true, this property prevents the element from receiving keyboard focus, making it inaccessible via keyboard navigation (such as the Tab key).
VvalueSets a new value for the element, or retrieves its current value. Use this property or method to programmatically access or update the element’s value in the DOM. Commonly applied to input fields, textareas, or form elements to manage user input or display dynamic content.

Events

CchangeThis event is triggered whenever the user changes the current selection within the component. It occurs whenever an item's selection state is updated—such as when a user selects, deselects, or switches between options—allowing you to respond to changes in the selected value or items.

Methods

CcloseCloses the dropdown menu, hiding all available options from view and returning the component to its default inactive state.
EensureVisibleEnsures that the currently selected item remains visible within its container, automatically scrolling the view if necessary to prevent the active item from being hidden or obscured.
OopenDisplays the dropdown menu, allowing users to view and select available options.
SselectSelects all text within the input field. If the input field has the readonly attribute, the method instead focuses the element without selecting its text.

Properties

animation"none" | "simple" | "advanced"

Gets or sets the animation mode. When this property is set to 'none', all animations are disabled. Setting it to other supported values enables the corresponding animation effects.

Allowed Values

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

Default value

"advanced"

Example

Set the animation property. 

 <smart-multi-input animation='none'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.animation = 'simple';

Get the animation property. 

 const multiinput = document.querySelector('smart-multi-input');
 let animation = multiinput.animation;

autoCompleteDelaynumber

Specifies the amount of time, in milliseconds, to wait before displaying the dropdown list of matching results after the user starts typing in the autocomplete field. This delay helps control how quickly suggestions appear, allowing for smoother user experience and reducing unnecessary search operations as the user types.

Default value

100

Example

Set the autoCompleteDelay property. 

 <smart-multi-input auto-complete-delay='50'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.autoCompleteDelay = 200;

Get the autoCompleteDelay property. 

 const multiinput = document.querySelector('smart-multi-input');
 let autoCompleteDelay = multiinput.autoCompleteDelay;

dataSourceany

Specifies the source of data used to populate the MultiInput component. The 'dataSource' property accepts one of the following:

- 'Array of Strings or Numbers:' Each element is rendered as a selectable item in the MultiInput list.
- 'Array of Objects:' Each object should contain properties, typically such as 'label' (the display text) and 'value' (the underlying value), to define the characteristics of each list item.
- 'Callback Function:' A function that returns an array of items in either of the above formats.

This flexible configuration allows you to define static lists, complex data structures, or dynamically load items as needed.

Try a demo showcasing the dataSource property.

Example

Set the dataSource property. 

 <smart-multi-input data-source='[{ label: "item 1", value: 1 }, { label: "item 2", value: 2 }]'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.dataSource = ["new item 1", "new item 2"];

Get the dataSource property. 

 const multiinput = document.querySelector('smart-multi-input');
 let dataSource = multiinput.dataSource;

disabledboolean

Specifies whether the element is active and interactive (enabled), or inactive and unresponsive to user interactions (disabled). When set to disabled, the element cannot be clicked, selected, or modified by the user.

Default value

false
Try a demo showcasing the disabled property.

Example

Set the disabled property. 

 <smart-multi-input disabled></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.disabled = false;

Get the disabled property. 

 const multiinput = document.querySelector('smart-multi-input');
 let disabled = multiinput.disabled;

dropDownButtonPosition"none" | "left" | "right"

Specifies the location where the dropdown button will appear relative to its parent element. Possible values typically include options such as 'left', 'right', 'top', or 'bottom', allowing you to control the visual placement of the button within the user interface.

Allowed Values

  • "none" - The drop down button is hidden and the element acts as a simple input.
  • "left" - A drop down button is displayed on the left side of the element. The element acts as a DropDownList or a ComboBox depending on the readonly property.
  • "right" - A drop down button is displayed on the right side of the element. The element acts as a DropDownList or a ComboBox depending on the readonly property.

Default value

"right"
Try a demo showcasing the dropDownButtonPosition property.

Example

Set the dropDownButtonPosition property. 

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

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.dropDownButtonPosition = 'bottom';

Get the dropDownButtonPosition property. 

 const multiinput = document.querySelector('smart-multi-input');
 let dropDownButtonPosition = multiinput.dropDownButtonPosition;

dropDownHeightstring | 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 associated CSS variable. If you provide a specific value (e.g., '200px', '20rem'), it will override the default CSS-controlled height and explicitly set the dropdown's height to the specified value.

Default value

""

Example

Set the dropDownHeight property. 

 <smart-multi-input drop-down-height='300'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.dropDownHeight = 500;

Get the dropDownHeight property. 

 const multiinput = document.querySelector('smart-multi-input');
 let dropDownHeight = multiinput.dropDownHeight;

dropDownWidthstring | number

Specifies the width of the dropdown menu. By default, this property is an empty string ('""'), meaning the dropdown's width is determined by a corresponding CSS variable. You can override this behavior by explicitly setting a value (e.g., '"200px"', '"50%"') to directly control the dropdown's width via inline styles, rather than relying on the CSS variable.

Default value

""

Example

Set the dropDownWidth property. 

 <smart-multi-input drop-down-width='300'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.dropDownWidth = 500;

Get the dropDownWidth property. 

 const multiinput = document.querySelector('smart-multi-input');
 let dropDownWidth = multiinput.dropDownWidth;

inputPurposestring

Specifies the intended purpose of the input field and indicates to the browser what type of information is expected from the user. This setting guides the browser in offering automated assistance, such as autocomplete suggestions, when the input is used within a form. The value corresponds directly to the standard HTML autocomplete attribute, which helps user agents (such as browsers) determine whether and how to autofill the field. You can assign values such as 'on' (enable autocomplete), 'off' (disable autocomplete), or more specific values like 'name', 'organization', 'street-address', 'email', and others, to optimize the autofill behavior and improve the user experience.

Default value

"off"

Example

Set the inputPurpose property. 

 <smart-multi-input input-purpose='on'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.inputPurpose = 'country';

Get the inputPurpose property. 

 const multiinput = document.querySelector('smart-multi-input');
 let inputPurpose = multiinput.inputPurpose;

itemsnumber

Specifies the maximum number of matched items to display in the dropdown list in response to a new autoComplete query. By default, up to 8 items will be shown in the dropdown. If more items match the query, only the first 8 will be visible, ensuring the dropdown remains concise and user-friendly. Adjust this value to control how many results are presented to users at once.

Default value

8

Example

Set the items property. 

 <smart-multi-input items='2'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.items = 5;

Get the items property. 

 const multiinput = document.querySelector('smart-multi-input');
 let items = multiinput.items;

unlockKeystring

Sets or retrieves the 'unlockKey' property, a unique key or code required to unlock access to the product’s features or full functionality. Use this property to provide the necessary unlock key when granting access, or to obtain the currently set unlock key.

Default value

""

Example

Set the unlockKey property. 

 <smart-multi-input unlock-key=''></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.unlockKey = '1111-2222-3333-4444-5555';

Get the unlockKey property. 

 const multiinput = document.querySelector('smart-multi-input');
 let unlockKey = multiinput.unlockKey;

localestring

Specifies or retrieves the current language setting for the component. This property determines which set of localized messages, defined in the messages property, will be displayed. When you update the language, the component automatically uses the corresponding message set from messages to reflect the selected language.

Default value

"en"

Example

Set the locale property. 

 <smart-multi-input locale='de'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.locale = 'en';

Get the locale property. 

 const multiinput = document.querySelector('smart-multi-input');
 let locale = multiinput.locale;

localizeFormatFunctionfunction

Callback function that allows developers to customize the formatting of messages returned by the Localization Module. This function receives the original message and relevant context, enabling dynamic modification—such as value interpolation, date and number formatting, or applying custom transformations—before the finalized message is delivered to the application.

Example

Set the localizeFormatFunction property. 

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

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.localizeFormatFunction = function(defaultMessage, message, messageArguments){return '...'};

Get the localizeFormatFunction property. 

 const multiinput = document.querySelector('smart-multi-input');
 let localizeFormatFunction = multiinput.localizeFormatFunction;

messagesobject

Defines or retrieves an object containing the set of text strings used within the widget, allowing these strings to be customized for different languages or regions. This property works together with the locale property to provide localization support, ensuring that UI labels, messages, and other user-facing text can be displayed appropriately based on the selected language.

Default value




"en": {

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

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

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

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

"moduleUndefined": "Module is undefined.",

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

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

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

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

}

Example

Set the messages property. 

 <smart-multi-input 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-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.messages = {"en":{"propertyUnknownType":"'{{name}}' property is with undefined 'type' member!","propertyInvalidValue":"Invalid '{{name}}' property value! Actual value: {{actualValue}}, Expected value: {{value}}!","propertyInvalidValueType":"Invalid '{{name}}' property value type! Actual type: {{actualType}}, Expected type: {{type}}!","elementNotInDOM":"Element does not exist in DOM! Please, add the element to the DOM, before invoking a method.","moduleUndefined":"Module is undefined.","missingReference":"{{elementType}}: Missing reference to {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser doesn't support HTMLTemplate elements.","invalidTemplate":"{{elementType}}: '{{property}}' property accepts a string that must match the id of an HTMLTemplate element from the DOM.","invalidNode":"{{elementType}}: Invalid parameter '{{node}}' when calling {{method}}."}};

Get the messages property. 

 const multiinput = document.querySelector('smart-multi-input');
 let messages = multiinput.messages;

minLengthnumber

Specifies the minimum number of characters a user must enter into the input field before the autocomplete functionality is activated. Once this threshold is reached, the dropdown will appear, displaying a list of items that match the user's input.

Default value

1

Example

Set the minLength property. 

 <smart-multi-input min-length='2'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.minLength = 0;

Get the minLength property. 

 const multiinput = document.querySelector('smart-multi-input');
 let minLength = multiinput.minLength;

namestring

Sets or retrieves the value of the element's "name" attribute. This attribute is used to identify form elements when submitting data through an HTML form. The value assigned to the "name" attribute is sent as the key in the key-value pair for the form data, allowing the server to process the input accordingly.

Default value

""

Example

Set the name property. 

 <smart-multi-input name='dropdown'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.name = 'dropDown2';

Get the name property. 

 const multiinput = document.querySelector('smart-multi-input');
 let name = multiinput.name;

openedboolean

Indicates whether the dropdown menu is currently open (true) or closed (false).

Default value

false

Example

Set the opened property. 

 <smart-multi-input opened></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.opened = false;

Get the opened property. 

 const multiinput = document.querySelector('smart-multi-input');
 let opened = multiinput.opened;

placeholderstring

Specifies the placeholder text displayed inside the input field before the user enters a value. This text typically provides a hint or example of the expected input.

Default value

""
Try a demo showcasing the placeholder property.

Example

Set the placeholder property. 

 <smart-multi-input placeholder='Empty'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.placeholder = 'Enter:';

Get the placeholder property. 

 const multiinput = document.querySelector('smart-multi-input');
 let placeholder = multiinput.placeholder;

querystring | number

Sets or retrieves the query string used to filter the list of items. This query is applied during the autoComplete operation to determine which items are shown based on the user's input. If the query is an empty string, all items from the data source are displayed without any filtering.

Default value

""

Example

Set the query property. 

 <smart-multi-input query='ABC'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.query = 'some query';

Get the query property. 

 const multiinput = document.querySelector('smart-multi-input');
 let query = multiinput.query;

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

Specifies the query mode used for the autocomplete feature. This property defines how user input is matched against available options, determining the matching algorithm (e.g., prefix, infix, or token matching) applied during autocomplete operations. Adjust this setting to control how search suggestions are generated and filtered based on the user's query.

Allowed Values

  • "contains" - Displays the items that contain the search query (case sensitive)
  • "containsIgnoreCase" - Displays the items that contain the search query (case insensitive)
  • "doesNotContain" - Displays the items that do not contain the search query (case sensitive)
  • "doesNotContainIgnoreCase" - Displays the items that do not contain the search query (case insensitive)
  • "equals" - Displays the items that are equal the search query (case sensitive)
  • "equalsIgnoreCase" - Displays the items that are equal the search query (case insensitive)
  • "startsWith" - Displays the items that start with the search query (case sensitive)
  • "startsWithIgnoreCase" - Displays the items that start with the search query (case insensitive)
  • "endsWith" - Displays the items that end with the search query (case sensitive)
  • "endsWithIgnoreCase" - Displays the items that start with the search query (case insensitive)

Default value

"containsIgnoreCase"

Example

Set the queryMode property. 

 <smart-multi-input query-mode='contains'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.queryMode = 'endsWith';

Get the queryMode property. 

 const multiinput = document.querySelector('smart-multi-input');
 let queryMode = multiinput.queryMode;

readonlyboolean

Controls whether the user can enter text directly into the input field. When dropDownButtonPosition is set to 'left' or 'right', the readonly property specifies how the element behaves if a dataSource is provided:
- If readonly is false, the element functions as a ComboBox, allowing users to either type custom text or select from the list.
- If readonly is true, the element acts as a DropDownList, restricting input to selection only from the available list items; custom text entry is not allowed.

Default value

false
Try a demo showcasing the readonly property.

Example

Set the readonly property. 

 <smart-multi-input readonly></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.readonly = false;

Get the readonly property. 

 const multiinput = document.querySelector('smart-multi-input');
 let readonly = multiinput.readonly;

rightToLeftboolean

Specifies or retrieves a value that determines whether the element’s alignment is configured for right-to-left (RTL) text direction, which is commonly used in languages such as Arabic or Hebrew. When enabled, the content within the element will align and flow appropriately to support RTL locales.

Default value

false
Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property. 

 <smart-multi-input right-to-left></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.rightToLeft = true;

Get the rightToLeft property. 

 const multiinput = document.querySelector('smart-multi-input');
 let rightToLeft = multiinput.rightToLeft;

separatorstring

Specifies the character or string used to separate multiple selected items within the input field. This delimiter controls how selected values are displayed and parsed, ensuring each item is clearly distinguished in the input.

Default value

","

Example

Set the separator property. 

 <smart-multi-input separator='-'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.separator = ',';

Get the separator property. 

 const multiinput = document.querySelector('smart-multi-input');
 let separator = multiinput.separator;

selectedValuesarray

Retrieves or assigns an array containing the currently selected values. Each item in the array represents a selected option, allowing for multiple selection handling.

selectAllboolean

Specifies whether an additional item should be displayed at the top of the options list. This item functions as a "Select All / Deselect All" control, allowing users to quickly select or unselect all available options in the list.

Default value

false

Example

Set the selectAll property. 

 <smart-multi-input select-all></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.selectAll = false;

Get the selectAll property. 

 const multiinput = document.querySelector('smart-multi-input');
 let selectAll = multiinput.selectAll;

sortedboolean

Specifies whether the items are arranged in alphabetical order. If set to true, the items will be sorted from A to Z; if set to false, the items will retain their original, unsorted order.

Default value

false

Example

Set the sorted property. 

 <smart-multi-input sorted></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.sorted = false;

Get the sorted property. 

 const multiinput = document.querySelector('smart-multi-input');
 let sorted = multiinput.sorted;

sortDirectionstring

Specifies the sorting order used when sort is enabled. Accepts either asc for ascending order or desc for descending order.

Default value

"asc"

Example

Set the sortDirection property. 

 <smart-multi-input sort-direction='desc'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.sortDirection = 'asc';

Get the sortDirection property. 

 const multiinput = document.querySelector('smart-multi-input');
 let sortDirection = multiinput.sortDirection;

themestring

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

Default value

""

Example

Set the theme property. 

 <smart-multi-input theme='blue'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.theme = 'red';

Get the theme property. 

 const multiinput = document.querySelector('smart-multi-input');
 let theme = multiinput.theme;

typestring

Specifies the type of input allowed in the field. The input type controls the kind of data the user can enter (such as text, email, number, password, etc.), which helps ensure data is entered in the correct format and may trigger specialized keyboards or validation behaviors on supported devices.

Default value

""

Example

Set the type property. 

 <smart-multi-input type='number'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.type = 'text';

Get the type property. 

 const multiinput = document.querySelector('smart-multi-input');
 let type = multiinput.type;

unfocusableboolean

When set to true, this property prevents the element from receiving keyboard focus, making it inaccessible via keyboard navigation (such as the Tab key).

Default value

false

Example

Set the unfocusable property. 

 <smart-multi-input unfocusable></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.unfocusable = false;

Get the unfocusable property. 

 const multiinput = document.querySelector('smart-multi-input');
 let unfocusable = multiinput.unfocusable;

valuestring

Sets a new value for the element, or retrieves its current value. Use this property or method to programmatically access or update the element’s value in the DOM. Commonly applied to input fields, textareas, or form elements to manage user input or display dynamic content.

Default value

""
Try a demo showcasing the value property.

Example

Set the value property. 

 <smart-multi-input value='value1'></smart-multi-input>

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

 const multiinput = document.querySelector('smart-multi-input');
 multiinput.value = 'value2';

Get the value property. 

 const multiinput = document.querySelector('smart-multi-input');
 let value = multiinput.value;

Events

changeCustomEvent

This event is triggered whenever the user changes the current selection within the component. It occurs whenever an item's selection state is updated—such as when a user selects, deselects, or switches between options—allowing you to respond to changes in the selected value or items.

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

Arguments

evCustomEvent
ev.detailObject
ev.detail.label - The label of the new selected item.
ev.detail.oldLabel - The label of the item that was previously selected before the event was triggered.
ev.detail.oldValue - The value of the item that was previously selected before the event was triggered.
ev.detail.value - The value of the new selected item.

Methods

isDefaultPrevented

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

Returns

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

preventDefault

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

stopPropagation

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

Example

Set up the event handler of change event. 

const multiinput = document.querySelector('smart-multi-input');
multiinput.addEventListener('change', function (event) {
    const detail = event.detail,
        label = detail.label,
        oldLabel = detail.oldLabel,
        oldValue = detail.oldValue,
        value = detail.value;

	// event handling code goes here.
})

Methods

close(): void

Closes the dropdown menu, hiding all available options from view and returning the component to its default inactive state.


Invoke the close method.

const multiinput = document.querySelector('smart-multi-input');
multiinput.close();

Try a demo showcasing the close method.

ensureVisible(): void

Ensures that the currently selected item remains visible within its container, automatically scrolling the view if necessary to prevent the active item from being hidden or obscured.


Invoke the ensureVisible method.

const multiinput = document.querySelector('smart-multi-input');
multiinput.ensureVisible();

open(): void

Displays the dropdown menu, allowing users to view and select available options.


Invoke the open method.

const multiinput = document.querySelector('smart-multi-input');
multiinput.open();

Try a demo showcasing the open method.

select(): void

Selects all text within the input field. If the input field has the readonly attribute, the method instead focuses the element without selecting its text.


Invoke the select method.

const multiinput = document.querySelector('smart-multi-input');
multiinput.select();