NumberInput JAVASCRIPT UI Component API

NumberInput Javascript API

Class

NumberInput

NumberInput

NumberInput specifies an input field where the user can enter a numbers.

Selector

smart-number-input

Properties

AanimationSpecifies or retrieves the current animation mode. When set to 'none', all animations are disabled. Setting this property to other supported values enables specific animation behaviors as defined by the available modes.
DdisabledControls whether the element is active and interactive (enabled) or inactive and unresponsive (disabled). When set to disabled, the element cannot be interacted with by users, and its associated actions or events will not trigger.
IinputPurposeSpecifies the intended purpose of the input field and indicates the level of permission granted to the user agent (such as a browser or password manager) to automatically assist in completing the input when used within a form. This attribute provides guidance to browsers about the type of data expected in the field, enabling features like autofill and enhanced accessibility. It corresponds to the standard HTML autocomplete attribute and accepts values such as 'on' (to enable autocomplete), 'off' (to disable autocomplete), or more specific tokens like 'name', 'email', 'organization', 'street-address', and others, enabling browsers to supply relevant information where appropriate. For a full list of valid values and their meanings, refer to the official HTML documentation for the autocomplete attribute.
UunlockKeyGets or sets the unlockKey, a unique string required to authenticate and unlock access to the product's features. Use this property to retrieve the current unlockKey or assign a new one to enable product usage.
LlocaleSpecifies or retrieves the current language code (e.g., "en", "fr") used for localization. This property should be used together with the messages property, which contains the corresponding translated text for each supported language. Setting this value determines which set of messages will be displayed to the user.
LlocalizeFormatFunctionA callback function that allows you to define a custom format for messages returned by the Localization Module. Use this to modify the structure, content, or appearance of localized messages before they are delivered to the application.
MmaxSpecifies the maximum numeric value that the input field can accept or display. Any value entered that exceeds this limit will be considered invalid.
MmessagesDefines or retrieves an object containing all the text strings used within the widget that can be localized. This enables the widget's user interface to display text in different languages, depending on the selected locale property. Use this object to provide translations for various widget messages, labels, and prompts to support internationalization.
MminSpecifies the minimum numerical value that users are allowed to enter or select within the input field. This value sets the lower limit for acceptable input, ensuring that any input below this threshold will be considered invalid.
NnameSets or retrieves the value of the element’s name attribute. The name attribute uniquely identifies form elements and is used as the key when submitting form data to a server. This allows the form data associated with this element to be sent and processed correctly when the form is submitted.
NnumberFormatSpecifies or retrieves the format in which the element's value is represented. This determines how the value is displayed to the user and how it is processed or stored in the underlying data model.
PplaceholderSpecifies the placeholder text that appears inside the input field before the user enters a value. This text provides a hint or example of the expected input format or content.
RreadonlySpecifies whether the user is allowed to type or modify text within the input field. If set to false, the input becomes read-only and the user cannot enter or change its contents.
RrightToLeftSets or retrieves a value that determines whether the element’s text direction and alignment are configured for right-to-left (RTL) languages, such as Arabic or Hebrew. When enabled, the element adjusts its layout and text flow to properly support RTL locales.
SstepSpecifies or retrieves the amount by which the element’s value increases or decreases when the user interacts with controls such as up/down arrows, sliders, or keyboard inputs. This determines the step interval for adjusting the element’s value.
TthemeSpecifies the visual theme to be applied to the element. Themes control the overall appearance, including colors, fonts, and styles, ensuring a consistent look and feel across the element. Selecting a theme customizes the design and user experience of the component.
UunfocusableIf set to true, the element will be excluded from the tab order and cannot receive keyboard focus. This means users will not be able to select the element using the Tab key or other keyboard navigation methods.
VvalueProvides a way to retrieve (get) or assign (set) the current value of the element, typically used for form fields such as input, textarea, or select elements. When used as a getter, it returns the element's current value as a string. When used as a setter, it updates the element's value to the specified string.

Events

CchangeThis event is triggered whenever the user selects a different item or modifies the current selection. It occurs each time the selection state changes, allowing you to respond dynamically to user interactions such as choosing an option from a dropdown menu, highlighting text, or switching between selectable elements.

Methods

GgetFormattedValueReturns the value converted to the specified format, ensuring that the output matches the required data type or structure (e.g., string, number, JSON object, date format) as requested by the caller.
GgetValueReturns the numeric value corresponding to the given input. If the input is a number, it is returned as-is; if the input is a string or another type that can be converted to a number, its numeric equivalent is returned. If the input cannot be converted to a number, the function may return NaN or throw an error, depending on implementation.
SselectSelects the entire text within the input field. If the input is set to readonly, the function will focus the element instead of selecting its text."
SsetValueAssigns a specified value to the input field, updating its displayed and underlying data. This ensures that the input reflects the current state or user-provided data within the form or component.

Properties

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

Specifies or retrieves the current animation mode. When set to 'none', all animations are disabled. Setting this property to other supported values enables specific animation behaviors as defined by the available modes.

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-number-input animation='none'></smart-number-input>

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.animation = 'simple';

Get the animation property. 

 const numberinput = document.querySelector('smart-number-input');
 let animation = numberinput.animation;

disabledboolean

Controls whether the element is active and interactive (enabled) or inactive and unresponsive (disabled). When set to disabled, the element cannot be interacted with by users, and its associated actions or events will not trigger.

Default value

false
Try a demo showcasing the disabled property.

Example

Set the disabled property. 

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

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.disabled = false;

Get the disabled property. 

 const numberinput = document.querySelector('smart-number-input');
 let disabled = numberinput.disabled;

inputPurposestring

Specifies the intended purpose of the input field and indicates the level of permission granted to the user agent (such as a browser or password manager) to automatically assist in completing the input when used within a form. This attribute provides guidance to browsers about the type of data expected in the field, enabling features like autofill and enhanced accessibility. It corresponds to the standard HTML autocomplete attribute and accepts values such as 'on' (to enable autocomplete), 'off' (to disable autocomplete), or more specific tokens like 'name', 'email', 'organization', 'street-address', and others, enabling browsers to supply relevant information where appropriate. For a full list of valid values and their meanings, refer to the official HTML documentation for the autocomplete attribute.

Default value

"off"

Example

Set the inputPurpose property. 

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

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.inputPurpose = 'country';

Get the inputPurpose property. 

 const numberinput = document.querySelector('smart-number-input');
 let inputPurpose = numberinput.inputPurpose;

unlockKeystring

Gets or sets the unlockKey, a unique string required to authenticate and unlock access to the product's features. Use this property to retrieve the current unlockKey or assign a new one to enable product usage.

Default value

""

Example

Set the unlockKey property. 

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

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

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

Get the unlockKey property. 

 const numberinput = document.querySelector('smart-number-input');
 let unlockKey = numberinput.unlockKey;

localestring

Specifies or retrieves the current language code (e.g., "en", "fr") used for localization. This property should be used together with the messages property, which contains the corresponding translated text for each supported language. Setting this value determines which set of messages will be displayed to the user.

Default value

"en"

Example

Set the locale property. 

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

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.locale = 'en';

Get the locale property. 

 const numberinput = document.querySelector('smart-number-input');
 let locale = numberinput.locale;

localizeFormatFunctionfunction

A callback function that allows you to define a custom format for messages returned by the Localization Module. Use this to modify the structure, content, or appearance of localized messages before they are delivered to the application.

Example

Set the localizeFormatFunction property. 

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

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

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

Get the localizeFormatFunction property. 

 const numberinput = document.querySelector('smart-number-input');
 let localizeFormatFunction = numberinput.localizeFormatFunction;

maxnumber

Specifies the maximum numeric value that the input field can accept or display. Any value entered that exceeds this limit will be considered invalid.

Default value

9999999999

Example

Set the max property. 

 <smart-number-input max='500'></smart-number-input>

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.max = 10;

Get the max property. 

 const numberinput = document.querySelector('smart-number-input');
 let max = numberinput.max;

messagesobject

Defines or retrieves an object containing all the text strings used within the widget that can be localized. This enables the widget's user interface to display text in different languages, depending on the selected locale property. Use this object to provide translations for various widget messages, labels, and prompts to support internationalization.

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

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.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 numberinput = document.querySelector('smart-number-input');
 let messages = numberinput.messages;

minnumber

Specifies the minimum numerical value that users are allowed to enter or select within the input field. This value sets the lower limit for acceptable input, ensuring that any input below this threshold will be considered invalid.

Default value

-9999999999

Example

Set the min property. 

 <smart-number-input min='-50'></smart-number-input>

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.min = 0;

Get the min property. 

 const numberinput = document.querySelector('smart-number-input');
 let min = numberinput.min;

namestring

Sets or retrieves the value of the element’s name attribute. The name attribute uniquely identifies form elements and is used as the key when submitting form data to a server. This allows the form data associated with this element to be sent and processed correctly when the form is submitted.

Default value

""

Example

Set the name property. 

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

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.name = 'dropDown2';

Get the name property. 

 const numberinput = document.querySelector('smart-number-input');
 let name = numberinput.name;

numberFormatany

Specifies or retrieves the format in which the element's value is represented. This determines how the value is displayed to the user and how it is processed or stored in the underlying data model.

Example

Set the numberFormat property. 

 <smart-number-input number-format='{ style: 'currency', currency: 'EUR' }'></smart-number-input>

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.numberFormat = { style: 'currency', currency: 'JPY' };

Get the numberFormat property. 

 const numberinput = document.querySelector('smart-number-input');
 let numberFormat = numberinput.numberFormat;

placeholderstring

Specifies the placeholder text that appears inside the input field before the user enters a value. This text provides a hint or example of the expected input format or content.

Default value

""
Try a demo showcasing the placeholder property.

Example

Set the placeholder property. 

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

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.placeholder = 'Enter:';

Get the placeholder property. 

 const numberinput = document.querySelector('smart-number-input');
 let placeholder = numberinput.placeholder;

readonlyboolean

Specifies whether the user is allowed to type or modify text within the input field. If set to false, the input becomes read-only and the user cannot enter or change its contents.

Default value

false

Example

Set the readonly property. 

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

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.readonly = false;

Get the readonly property. 

 const numberinput = document.querySelector('smart-number-input');
 let readonly = numberinput.readonly;

rightToLeftboolean

Sets or retrieves a value that determines whether the element’s text direction and alignment are configured for right-to-left (RTL) languages, such as Arabic or Hebrew. When enabled, the element adjusts its layout and text flow to properly support RTL locales.

Default value

false
Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property. 

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

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.rightToLeft = true;

Get the rightToLeft property. 

 const numberinput = document.querySelector('smart-number-input');
 let rightToLeft = numberinput.rightToLeft;

stepnumber

Specifies or retrieves the amount by which the element’s value increases or decreases when the user interacts with controls such as up/down arrows, sliders, or keyboard inputs. This determines the step interval for adjusting the element’s value.

Default value

1

Example

Set the step property. 

 <smart-number-input step='2'></smart-number-input>

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.step = 5;

Get the step property. 

 const numberinput = document.querySelector('smart-number-input');
 let step = numberinput.step;

themestring

Specifies the visual theme to be applied to the element. Themes control the overall appearance, including colors, fonts, and styles, ensuring a consistent look and feel across the element. Selecting a theme customizes the design and user experience of the component.

Default value

""

Example

Set the theme property. 

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

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.theme = 'red';

Get the theme property. 

 const numberinput = document.querySelector('smart-number-input');
 let theme = numberinput.theme;

unfocusableboolean

If set to true, the element will be excluded from the tab order and cannot receive keyboard focus. This means users will not be able to select the element using the Tab key or other keyboard navigation methods.

Default value

false

Example

Set the unfocusable property. 

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

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.unfocusable = false;

Get the unfocusable property. 

 const numberinput = document.querySelector('smart-number-input');
 let unfocusable = numberinput.unfocusable;

valueany

Provides a way to retrieve (get) or assign (set) the current value of the element, typically used for form fields such as input, textarea, or select elements. When used as a getter, it returns the element's current value as a string. When used as a setter, it updates the element's value to the specified string.

Default value

0

Example

Set the value property. 

 <smart-number-input value='6'></smart-number-input>

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

 const numberinput = document.querySelector('smart-number-input');
 numberinput.value = 11;

Get the value property. 

 const numberinput = document.querySelector('smart-number-input');
 let value = numberinput.value;

Events

changeCustomEvent

This event is triggered whenever the user selects a different item or modifies the current selection. It occurs each time the selection state changes, allowing you to respond dynamically to user interactions such as choosing an option from a dropdown menu, highlighting text, or switching between selectable elements.

  • 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 numberinput = document.querySelector('smart-number-input');
numberinput.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

getFormattedValue( value: string | number, format?: any): string

Returns the value converted to the specified format, ensuring that the output matches the required data type or structure (e.g., string, number, JSON object, date format) as requested by the caller.

Arguments

valuestring | number

The value to be formatted by the method.

format?any

The object that contains the formatting properties. The argument should contain Intl.NumberFormat valid properties. For example, { style: 'currency', currency: 'EUR' }

Returnsstring

Invoke the getFormattedValue method.

const numberinput = document.querySelector('smart-number-input');
const result = numberinput.getFormattedValue();

getValue(): number

Returns the numeric value corresponding to the given input. If the input is a number, it is returned as-is; if the input is a string or another type that can be converted to a number, its numeric equivalent is returned. If the input cannot be converted to a number, the function may return NaN or throw an error, depending on implementation.

Returnsnumber

Invoke the getValue method.

const numberinput = document.querySelector('smart-number-input');
const result = numberinput.getValue();

select(): void

Selects the entire text within the input field. If the input is set to readonly, the function will focus the element instead of selecting its text."


Invoke the select method.

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

setValue( value: string | number): void

Assigns a specified value to the input field, updating its displayed and underlying data. This ensures that the input reflects the current state or user-provided data within the form or component.

Arguments

valuestring | number

The value to be set.


Invoke the setValue method.

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