Input Javascript API

Class

Input

Input specifies an input field where the user can enter data. Auto-complete options are displayed for easier input.

Selector

smart-input

Properties

Events

Methods

Properties

autoCompleteDelaynumber

Specifies the amount of time, in milliseconds, to wait before displaying the dropdown list of matching suggestions after the user interacts with the autocomplete input. This delay helps control how quickly the dropdown appears, improving user experience by preventing it from opening too rapidly as users type.

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

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

 input.autoCompleteDelay = 200;

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

 let autoCompleteDelay = input.autoCompleteDelay;

dataSourceany

Specifies the data source that will be used to populate the Input component. The dataSource property accepts multiple formats:

- 'Array of Primitives:' An array of strings or numbers, where each element represents a single list item.
- 'Array of Objects:' An array of objects, where each object defines the properties of a list item. The recognized fields for each item object include:
- label (string): The display text for the item.
- value (string | number): The underlying value associated with the item.
- selected (boolean): Indicates whether the item is initially selected.
- prefix (string): HTML content to display before the label.
- suffix (string): HTML content to display after the label.
- title (string): Additional descriptive text, typically used for tooltips.
- 'Callback Function:' A function that returns an array of items in either of the formats described above, allowing for dynamic or asynchronous data loading.

The prefix and suffix fields can contain HTML, which is rendered respectively before and after the item's label. This allows for additional icons, badges, or formatting as needed to enhance the list item's visual presentation.

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

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

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

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

 let dataSource = input.dataSource;

disabledboolean

Controls whether the element is active and interactive (enabled) or inactive and unresponsive to user interactions (disabled). When disabled, the element cannot be interacted with or triggered by the user.

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

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

 input.disabled = false;

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

 let disabled = input.disabled;

dropDownClassListarray

Allows you to specify extra CSS class names that will be applied to the Input dropdown element, enabling custom styling or theming beyond the default classes.

 <smart-input drop-down-class-list='my-custom-input-class-name'></smart-input>

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

 input.dropDownClassList = [];

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

 let dropDownClassList = input.dropDownClassList;

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

Specifies the placement of the dropdown button relative to its container or trigger element, such as positioning it above, below, to the left, or to the right. This affects where the dropdown appears on the user interface when activated.

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.

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

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

 input.dropDownButtonPosition = 'bottom';

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

 let dropDownButtonPosition = input.dropDownButtonPosition;

dropDownOpenPosition"auto" | "top" | "bottom"

Specifies the placement of the dropdown menu relative to its trigger element when opened, such as above, below, left, or right.

Allowed Values

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

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

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

 input.dropDownOpenPosition = 'bottom';

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

 let dropDownOpenPosition = input.dropDownOpenPosition;

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 corresponding CSS variable. To override the default behavior and set a custom height, assign a specific value (such as "200px" or "50%") to this property. If left unset, the component relies on the CSS variable to control its height.

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

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

 input.dropDownHeight = 500;

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

 let dropDownHeight = input.dropDownHeight;

dropDownWidthstring | number

Defines the width of the dropdown menu. By default, this property is set to an empty string (""). When left empty, the dropdown's width is determined by a corresponding CSS variable, allowing you to control its sizing through your stylesheet. To specify a fixed width, provide a valid CSS width value (e.g., "200px", "100%"). If not specified, the component will fallback to the CSS variable for its width.

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

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

 input.dropDownWidth = 500;

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

 let dropDownWidth = input.dropDownWidth;

inputPurposestring

Specifies the purpose of the input field and instructs the browser on both the type of data expected and the level of permission granted to automatically assist the user in filling out the form element. This property directly maps to the standard HTML autocomplete attribute, which helps improve user experience by enabling browsers to suggest or autofill relevant data, such as a user’s name, organization, street address, and more. Common values include 'on' (enables autocomplete), 'off' (disables autocomplete), as well as context-specific tokens like 'name', 'email', 'organization', and 'street-address', among others. Using the appropriate value enhances form usability, accuracy, and accessibility.

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

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

 input.inputPurpose = 'country';

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

 let inputPurpose = input.inputPurpose;

itemsnumber

Specifies the maximum number of matching items that will be displayed in the dropdown menu after a new auto-complete query is performed. By default, the dropdown will show up to 8 items. If the number of matched items exceeds this limit, only the first 8 results will be visible, and additional matches will not be shown unless this value is increased.

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

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

 input.items = 5;

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

 let items = input.items;

unlockKeystring

Retrieves or assigns the unlockKey value used to grant access to the product. The unlockKey serves as a security credential required to unlock and enable product functionality.

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

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

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

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

 let unlockKey = input.unlockKey;

localestring

Specifies or retrieves the current language setting, which determines the localization to be used for displaying content. This property works together with the messages property to select and present language-specific messages or text strings. Setting this property updates the language used throughout the interface, while getting the property returns the currently active language code (e.g., "en", "fr", "es").

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

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

 input.locale = 'en';

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

 let locale = input.locale;

localizeFormatFunctionfunction

Callback function that allows you to define a custom format for messages returned by the Localization Module. Use this to modify or structure localized messages before they are delivered to the application, such as adding context, adjusting placeholders, or applying additional formatting logic.

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

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

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

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

 let localizeFormatFunction = input.localizeFormatFunction;

messagesobject

Defines or retrieves an object containing customizable text strings displayed by the widget, enabling localization for different languages and regions. This property works together with the locale property to allow the widget’s user interface labels, messages, and prompts to be easily translated and adapted for international audiences.

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

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

 input.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}}."}};

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

 let messages = input.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 open and display a list of matching items based on the user's input.

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

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

 input.minLength = 0;

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

 let minLength = input.minLength;

namestring

Sets or retrieves the value of the element’s name attribute. The name attribute uniquely identifies form elements when submitting data through an HTML form. It is used as the key for the form data sent to the server, allowing server-side scripts to access the corresponding value.

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

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

 input.name = 'dropDown2';

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

 let name = input.name;

openedboolean

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

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

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

 input.opened = false;

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

 let opened = input.opened;

placeholderstring

Specifies the placeholder text displayed inside the input field when it is empty, providing guidance or an example to the user about the expected input format or content.

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

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

 input.placeholder = 'Enter:';

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

 let placeholder = input.placeholder;

querystring | number

Defines or retrieves the filter query used to determine which items are displayed. This query is utilized by the autoComplete operation to match and return relevant items from the data source. If the query is set to an empty string, no filtering is applied, and all available items from the data source are shown.

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

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

 input.query = 'some query';

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

 let query = input.query;

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

Specifies the autocomplete query mode, which defines how search suggestions are generated. This property controls the matching algorithm used during autocomplete operations, such as whether suggestions are based on prefix, infix, or exact matches within the input text. Adjusting this property allows you to tailor the autocomplete behavior to best suit your application's search experience.

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)

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

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

 input.queryMode = 'endsWith';

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

 let queryMode = input.queryMode;

readonlyboolean

Specifies whether the user can enter text directly into the input field. When dropDownButtonPosition is set to 'left' or 'right', the readonly property controls the behavior of the input when a dataSource is provided:

• If readonly is false, the element functions as a ComboBox, allowing users to either select an option from the dropdown or type their own input.


• If readonly is true, the element acts as a DropDownList, restricting user input to only the items available in the dataSource.

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

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

 input.readonly = false;

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

 let readonly = input.readonly;

rightToLeftboolean

Specifies or retrieves whether the element's text alignment and layout are configured for right-to-left (RTL) languages, such as Arabic or Hebrew. When enabled, the element's content will display in a direction suitable for RTL locales, ensuring proper reading order and alignment for users of these languages.

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

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

 input.rightToLeft = true;

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

 let rightToLeft = input.rightToLeft;

sortedboolean

Specifies whether the items should be arranged in alphabetical order. If enabled, the items will be sorted from A to Z based on their names; if disabled, the original order will be preserved.

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

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

 input.sorted = false;

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

 let sorted = input.sorted;

sortDirectionstring

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

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

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

 input.sortDirection = 'asc';

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

 let sortDirection = input.sortDirection;

selectedIndexnumber

Specifies the index of the currently selected item within a list or array. This value indicates which item is active or highlighted, typically starting from zero for the first item.

 <smart-input selected-index='2'></smart-input>

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

 input.selectedIndex = 0;

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

 let selectedIndex = input.selectedIndex;

selectedValuestring | number

Specifies the currently selected value from the available options. This property indicates which option is active or chosen by the user within the component.

 <smart-input selected-value='2'></smart-input>

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

 input.selectedValue = 0;

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

 let selectedValue = input.selectedValue;

themestring

Specifies the visual theme applied to the element. The selected theme controls the element’s overall appearance, including colors, fonts, and styling, to ensure consistency with the application's design guidelines.

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

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

 input.theme = 'red';

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

 let theme = input.theme;

typestring

Specifies the type of input expected by the field. Setting the input type controls the kind of data users can enter (e.g., text, number, email, password), impacts the on-screen keyboard on mobile devices, and enables input validation based on the chosen type.

 <smart-input type='blue'></smart-input>

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

 input.type = 'red';

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

 let type = input.type;

unfocusableboolean

When set to true, this property ensures that the element is not focusable and cannot receive keyboard or programmatic focus.

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

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

 input.unfocusable = false;

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

 let unfocusable = input.unfocusable;

valuestring

Sets a new value for the element or retrieves its current value, depending on how the function is used.

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

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

 input.value = 'value2';

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

 let value = input.value;

Events

changeCustomEvent

This event is triggered whenever the user changes the current selection, such as selecting different text, items, or options within the interface. It provides an opportunity to respond dynamically to user interactions involving selection changes.

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

Arguments

const input = document.querySelector('smart-input');
input.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.
})

changingCustomEvent

This event is triggered whenever the user releases a key (keyup) while typing in the Input field, but only if the input’s value has actually changed since the last event.

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

Arguments

const input = document.querySelector('smart-input');
input.addEventListener('changing', function (event) {
    const detail = event.detail,
        oldValue = detail.oldValue,
        value = detail.value;

	// event handling code goes here.
})

openCustomEvent

This event is triggered immediately when the popup component becomes visible to the user, signaling that the popup has been successfully opened and rendered in the DOM. It can be used to execute custom logic or initialize content whenever the popup appears.

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

Arguments

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

closeCustomEvent

This event is triggered immediately when the popup window is closed, either by user action (such as clicking the close button) or programmatically via code. It provides an opportunity to execute cleanup tasks, update application state, or respond to the closure of the popup.

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

Arguments

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

itemClickCustomEvent

This event is triggered whenever a user selects (clicks on) an item within the popup list. It allows you to respond to user interactions by executing specific logic or actions when a particular popup list item is chosen.

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

Arguments

const input = document.querySelector('smart-input');
input.addEventListener('itemClick', function (event) {
    const detail = event.detail,
        item = detail.item,
        label = detail.label,
        value = detail.value;

	// event handling code goes here.
})

Methods

close(): void

Closes the currently open dropdown menu, hiding its options from view and reverting the interface to its default state.

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

ensureVisible(): void

Ensures that the currently selected item remains visible within the viewport by automatically scrolling the container as needed. This guarantees that users can always see the active item, even when navigating through a list with limited onscreen space.

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

open(): void

Expands the dropdown menu to display all available options for user selection.

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

select(): void

Enhances user interaction by automatically focusing the input element and selecting its text. If the input is set to readonly, the element receives focus but its text is not selected, ensuring consistent behavior based on the input's state.

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

selectItem( value: string | number): void

Selects an item from a data source based on its value.

If your data source is a simple array of strings (e.g., `['Item 1', 'Item 2', 'Item 3']`), you can select an item by passing the exact string value, such as `'Item 1'`.

If your data source is an array of objects with `label` and `value` properties (e.g., `[{ label: 'First', value: 1 }, { label: 'Second', value: 2 }]`), you should pass the corresponding `value` property (e.g., `1` for the first item) when calling `selectItem`.

This method automatically locates and selects the item whose value matches the argument you provide, whether the values are strings or object properties.

Arguments

valuestring | number

The item's value when the item is an object or string when the item is a string item.

const input = document.querySelector('smart-input');
input.selectItem("1","2");

getItem( value: string | number): any

Retrieves an item from the data source by matching its value. For example, if your data source is an array of strings like ['Item 1', 'Item 2', 'Item 3'], you can retrieve an item by passing its exact string value, such as 'Item 1'. If your data source is an array of objects with properties such as { label: 'Item 1', value: 'item1' }, you should pass the specific value (e.g., 'item1') when calling selectItem. The method will return the corresponding item whose value matches the argument you provide.

Arguments

valuestring | number

The item's value when the item is an object or string when the item is a string item.

Returnsany

const input = document.querySelector('smart-input');
const result = input.getItem("1","2");

getSelectedItem( value: string | number): any

Retrieves the currently selected item from the data source.
- If your data source is a simple array of strings—such as `['Item 1', 'Item 2', 'Item 3']`—and the user selects the second item, this method will return `'Item 2'`.
- If your data source is an array of objects with properties like `{ label, value }`, the method returns the `value` property of the selected object. For example, with a data source of `[ { label: 'First', value: 1 }, { label: 'Second', value: 2 } ]` and the user selects "Second", the method returns `2`.

This ensures the method always returns the relevant value associated with the selected option, based on the structure of the data source.

Arguments

valuestring | number

The item's value when the item is an object or string when the item is a string item.

Returnsany

const input = document.querySelector('smart-input');
const result = input.getSelectedItem("1","2");