MaskedTextBox JAVASCRIPT UI Component API

MaskedTextBox Javascript API

Class

MaskedTextBox

MaskedTextBox

MaskedTextBox uses a mask to control the input of the user.

Selector

smart-masked-text-box

Properties

AanimationSpecifies or retrieves the current animation mode for the element. When set to 'none', all animations are disabled for the element, resulting in immediate changes without any animated transitions. If another value is assigned, the corresponding animation mode will be applied, controlling how transitions or visual effects are rendered.
AallowPromptAsInputChecks if the specified promptChar character is recognized as a valid input, allowing the user to enter it into the field. If promptChar is considered valid, it will be accepted and processed as part of the user’s input; otherwise, it will be rejected.
AasciiOnlySpecifies whether the input field restricts user entries to characters within the standard ASCII character set (codes 0–127), excluding all non-ASCII symbols, accented letters, and characters from other languages.
AautoFocusDetermines if the input element automatically receives focus when the page loads, allowing users to begin typing immediately without manually selecting the field.
AautoShowMaskControls whether the input mask is displayed or hidden when the input field receives or loses focus, regardless of whether a placeholder is specified. This setting applies even if no placeholder attribute is present on the input element.
CcutCopyMaskFormatSpecifies whether formatting characters (such as literals and prompt symbols) included in an input mask are also copied to the clipboard when performing cut or copy operations. If enabled, both the user's input and the input mask characters will be included in the clipboard data; if disabled, only the user's input is copied.
DdisabledDetermines whether the element is interactive or inactive. When enabled, users can interact with the element; when disabled, the element appears dimmed and does not respond to user input.
EenterKeyBehaviorDefines the action performed when the "Enter" key is pressed. Possible values include "submit" (submits the form), "newline" (inserts a new line), or "none" (no action). The default value is "submit".
HhidePromptOnLeaveControls whether the prompt character in the input mask is hidden when the masked text box loses focus. When set to true, the prompt character will not be visible in the textbox after it loses focus; when set to false, the prompt character remains visible even when the textbox is not focused. This helps manage what users see when interacting with the masked input field.
HhintDisplays supplementary helper text beneath the element. This hint appears exclusively when the element is focused, providing contextual guidance to the user during input or interaction. The helper text is hidden when the element is not focused, ensuring a clean interface when not needed.
IisOverwriteModeSpecifies whether new user input will replace the current input value entirely, or if it will be appended to or combined with the existing value. When enabled, any new input overwrites the existing content; when disabled, new input is added to the existing value without removing it.
LlabelDisplays a label positioned above the element. The label remains constantly visible, providing clear identification for the associated element at all times.
UunlockKeyDefines or retrieves the unlockKey, a unique identifier or code required to activate and access the product's full features.
LlocaleSpecifies or retrieves the current language setting for the application or component. This property determines which set of localized messages from the messages object will be used for display, enabling support for multiple languages. When you set the language, the corresponding message translations from the messages property are applied automatically.
LlocalizeFormatFunctionA callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify translated strings—such as injecting dynamic values, changing case, or applying additional formatting—before they are displayed to users.
MmaskSpecifies the input mask pattern that determines the allowed format and structure of user input. This ensures that the entered data matches the required criteria, such as a phone number, date, or custom format.
MmaskCompletedSpecifies whether every required field defined by the mask has been filled in with valid data. Returns true if all required fields are populated; otherwise, returns false.
MmaskFullSpecifies whether every required and optional field defined by the mask has been filled with a value. If true, all fields that the mask references are populated; if false, at least one referenced field remains unset.
MmaxLengthSpecifies the upper limit on the number of characters that a user is allowed to input. If the user attempts to enter more characters than this limit, additional input will be prevented or ignored. This property is commonly used in form fields to enforce data length constraints and ensure consistent data entry.
MmessagesDefines or retrieves an object containing customizable text strings used within the widget, allowing for localization of user interface elements. This property works in conjunction with the locale property to provide translations and adapt the widget's display language to different regions or languages. Use this to specify or override default labels, messages, or prompts shown in the widget.
NnameSets or retrieves the value of the element's name attribute. The name attribute identifies the element within an HTML form, ensuring its value is included in the form data sent to the server upon submission. This is essential for correctly processing user input on the backend.
PplaceholderSpecifies the placeholder text displayed in the input field when both the value and mask properties are unset or empty. This text provides users with a hint or example of the expected input format until they enter a value.
PpromptCharSpecifies the character used as the placeholder in the input mask for the element. This character indicates where user input is expected within the input field.
RreadonlyWhen the element is set to readonly, users can view its content but cannot modify or interact with it in any way. This ensures that the element’s value remains unchanged by user input, while still being visible on the page.
RrejectInputOnFirstFailureSpecifies whether the parsing process should immediately halt upon encountering the first invalid character in the user input, or continue attempting to parse the remaining input.
RrequiredIndicates that this input field is required and cannot be left empty; users must provide a value before the form can be successfully submitted.
RresetOnPromptControls whether entering a character in the input field that matches the prompt character will reset the currently selected value. This setting is relevant only when allowPromptAsInput is enabled, meaning the prompt character can be used as user input. When enabled, if the user types the prompt character, the input’s selected value will be cleared; otherwise, the value remains unchanged.
RresetOnSpaceSpecifies whether pressing the spacebar will clear the currently selected value in the input field. When set to true, pressing the space key will reset (clear) the selection; when set to false, the value remains unchanged.
RrightToLeftSpecifies or retrieves a Boolean value that determines whether the element’s content is aligned to support right-to-left (RTL) languages, such as Arabic or Hebrew. When set to true, the element’s text direction and alignment are adjusted to display content appropriately for RTL locales.
SselectAllOnFocusDetermines if the entire value of the input field will be automatically highlighted (selected) when the input receives focus, allowing users to easily replace or copy the existing content.
TtextMaskFormatSpecifies whether the value entered in the input field should include or exclude the static characters (prompts and literals) defined by the input mask. When enabled, the resulting value will contain these mask characters; otherwise, only the user input (without mask characters) will be stored.
TthemeSpecifies the visual theme to be applied. The theme controls the overall appearance—including colors, fonts, and style—of the element, ensuring a consistent and customizable look and feel.
UunfocusableIf this property is set to true, the element will be excluded from keyboard navigation and cannot receive focus, either by tabbing or programmatically.
VvalueGets the current value of the element or sets a new value for the element, depending on how the method is used. When called without arguments, it returns the element's current value. When provided with a value as an argument, it updates the element with the specified value. Commonly used with form input elements.
VvalidationA callback function that enables you to define custom validation logic for the input value. This function receives the input value as an argument and should return a boolean value: return true if the value is considered valid, or false if it is invalid. If the function returns false, the input will be treated as invalid and may trigger corresponding validation error messages or prevent form submission. Use this to implement validations that go beyond the default rules.

Events

CchangeThis event is triggered whenever the user modifies the content of the Text Box, such as by typing, deleting, or pasting text. It fires each time the value of the Text Box changes, allowing you to respond to user input in real-time.
CchangingThis event is triggered whenever a key is released (on key up) in the MaskedTextBox control and the input value has been modified as a result. It only fires if the key up event causes a change in the current value of the MaskedTextBox, allowing you to respond specifically to user edits in real-time.
VvalidationThis event is triggered when the validation property is set. It indicates the result of the validation process—specifically, whether the validation completed successfully (true) or failed (false). Use this event to respond to changes in the validation state of the associated data or form.

Methods

FfocusSets keyboard and screen reader focus to the specified element, making it the active element for user interactions such as typing or accessibility navigation.
BblurApplies a blur effect to the element, causing its content and any child elements to appear out of focus by softening edges and details. The degree of blur can typically be adjusted to achieve the desired level of visual obscurity.

Properties

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

Specifies or retrieves the current animation mode for the element. When set to 'none', all animations are disabled for the element, resulting in immediate changes without any animated transitions. If another value is assigned, the corresponding animation mode will be applied, controlling how transitions or visual effects are rendered.

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-masked-text-box animation='none'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.animation = 'simple';

Get the animation property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let animation = maskedtextbox.animation;

allowPromptAsInputboolean

Checks if the specified promptChar character is recognized as a valid input, allowing the user to enter it into the field. If promptChar is considered valid, it will be accepted and processed as part of the user’s input; otherwise, it will be rejected.

Default value

false

Example

Set the allowPromptAsInput property. 

 <smart-masked-text-box allow-prompt-as-input></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.allowPromptAsInput = false;

Get the allowPromptAsInput property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let allowPromptAsInput = maskedtextbox.allowPromptAsInput;

asciiOnlyboolean

Specifies whether the input field restricts user entries to characters within the standard ASCII character set (codes 0–127), excluding all non-ASCII symbols, accented letters, and characters from other languages.

Default value

false

Example

Set the asciiOnly property. 

 <smart-masked-text-box ascii-only></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.asciiOnly = false;

Get the asciiOnly property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let asciiOnly = maskedtextbox.asciiOnly;

autoFocusboolean

Determines if the input element automatically receives focus when the page loads, allowing users to begin typing immediately without manually selecting the field.

Default value

false

Example

Set the autoFocus property. 

 <smart-masked-text-box auto-focus></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.autoFocus = false;

Get the autoFocus property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let autoFocus = maskedtextbox.autoFocus;

autoShowMaskboolean

Controls whether the input mask is displayed or hidden when the input field receives or loses focus, regardless of whether a placeholder is specified. This setting applies even if no placeholder attribute is present on the input element.

Default value

false

Example

Set the autoShowMask property. 

 <smart-masked-text-box auto-show-mask></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.autoShowMask = false;

Get the autoShowMask property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let autoShowMask = maskedtextbox.autoShowMask;

cutCopyMaskFormat"excludePromptAndLiterals" | "includePrompt" | "includeLiterals" | "includePromptAndLiterals"

Specifies whether formatting characters (such as literals and prompt symbols) included in an input mask are also copied to the clipboard when performing cut or copy operations. If enabled, both the user's input and the input mask characters will be included in the clipboard data; if disabled, only the user's input is copied.

Allowed Values

  • "excludePromptAndLiterals" - Excludes the prompt and literal characters when copy/cut text from the input.
  • "includePrompt" - Includes the prompt character along with the rest of the input.
  • "includeLiterals" - Includes all literal characters from the input.
  • "includePromptAndLiterals" - Includes the prompt and literal characters from the input.

Default value

"excludePromptAndLiterals"
Try a demo showcasing the cutCopyMaskFormat property.

Example

Set the cutCopyMaskFormat property. 

 <smart-masked-text-box cut-copy-mask-format='includePrompt'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.cutCopyMaskFormat = 'includeLiterals';

Get the cutCopyMaskFormat property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let cutCopyMaskFormat = maskedtextbox.cutCopyMaskFormat;

disabledboolean

Determines whether the element is interactive or inactive. When enabled, users can interact with the element; when disabled, the element appears dimmed and does not respond to user input.

Default value

false

Example

Set the disabled property. 

 <smart-masked-text-box disabled></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.disabled = false;

Get the disabled property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let disabled = maskedtextbox.disabled;

enterKeyBehavior"clearOnSubmit" | "submit"

Defines the action performed when the "Enter" key is pressed. Possible values include "submit" (submits the form), "newline" (inserts a new line), or "none" (no action). The default value is "submit".

Allowed Values

  • "clearOnSubmit" - Clears the value of the input on Submit.
  • "submit" - Submits the value of the input but doesn't clear it.

Default value

"submit"

Example

Set the enterKeyBehavior property. 

 <smart-masked-text-box enter-key-behavior='newLine'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.enterKeyBehavior = 'submit';

Get the enterKeyBehavior property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let enterKeyBehavior = maskedtextbox.enterKeyBehavior;

hidePromptOnLeaveboolean

Controls whether the prompt character in the input mask is hidden when the masked text box loses focus. When set to true, the prompt character will not be visible in the textbox after it loses focus; when set to false, the prompt character remains visible even when the textbox is not focused. This helps manage what users see when interacting with the masked input field.

Default value

false
Try a demo showcasing the hidePromptOnLeave property.

Example

Set the hidePromptOnLeave property. 

 <smart-masked-text-box hide-prompt-on-leave></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.hidePromptOnLeave = false;

Get the hidePromptOnLeave property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let hidePromptOnLeave = maskedtextbox.hidePromptOnLeave;

hintstring

Displays supplementary helper text beneath the element. This hint appears exclusively when the element is focused, providing contextual guidance to the user during input or interaction. The helper text is hidden when the element is not focused, ensuring a clean interface when not needed.

Default value

""
Try a demo showcasing the hint property.

Example

Set the hint property. 

 <smart-masked-text-box hint='Helper text'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.hint = 'Hint';

Get the hint property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let hint = maskedtextbox.hint;

isOverwriteModeboolean

Specifies whether new user input will replace the current input value entirely, or if it will be appended to or combined with the existing value. When enabled, any new input overwrites the existing content; when disabled, new input is added to the existing value without removing it.

Default value

false
Try a demo showcasing the isOverwriteMode property.

Example

Set the isOverwriteMode property. 

 <smart-masked-text-box is-overwrite-mode></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.isOverwriteMode = false;

Get the isOverwriteMode property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let isOverwriteMode = maskedtextbox.isOverwriteMode;

labelstring

Displays a label positioned above the element. The label remains constantly visible, providing clear identification for the associated element at all times.

Default value

""
Try a demo showcasing the label property.

Example

Set the label property. 

 <smart-masked-text-box label='Helper text'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.label = 'Hint';

Get the label property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let label = maskedtextbox.label;

unlockKeystring

Defines or retrieves the unlockKey, a unique identifier or code required to activate and access the product's full features.

Default value

""

Example

Set the unlockKey property. 

 <smart-masked-text-box unlock-key=''></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.unlockKey = '1111-2222-3333-4444-5555';

Get the unlockKey property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let unlockKey = maskedtextbox.unlockKey;

localestring

Specifies or retrieves the current language setting for the application or component. This property determines which set of localized messages from the messages object will be used for display, enabling support for multiple languages. When you set the language, the corresponding message translations from the messages property are applied automatically.

Default value

"en"

Example

Set the locale property. 

 <smart-masked-text-box locale='de'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.locale = 'fr';

Get the locale property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let locale = maskedtextbox.locale;

localizeFormatFunctionfunction | null

A callback function that allows you to customize the formatting of messages returned by the Localization Module. Use this to modify translated strings—such as injecting dynamic values, changing case, or applying additional formatting—before they are displayed to users.

Example

Set the localizeFormatFunction property. 

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

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.localizeFormatFunction = function(defaultMessage, message, messageArguments){return '...'};

Get the localizeFormatFunction property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let localizeFormatFunction = maskedtextbox.localizeFormatFunction;

maskstring

Specifies the input mask pattern that determines the allowed format and structure of user input. This ensures that the entered data matches the required criteria, such as a phone number, date, or custom format.

Default value

"#####"
Try a demo showcasing the mask property.

Example

Set the mask property. 

 <smart-masked-text-box mask='##-###'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.mask = '(##)###';

Get the mask property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let mask = maskedtextbox.mask;

maskCompletedboolean

Specifies whether every required field defined by the mask has been filled in with valid data. Returns true if all required fields are populated; otherwise, returns false.

Default value

false

Example

Set the maskCompleted property. 

 <smart-masked-text-box mask-completed></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.maskCompleted = false;

Get the maskCompleted property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let maskCompleted = maskedtextbox.maskCompleted;

maskFullboolean

Specifies whether every required and optional field defined by the mask has been filled with a value. If true, all fields that the mask references are populated; if false, at least one referenced field remains unset.

Default value

false

Example

Set the maskFull property. 

 <smart-masked-text-box mask-full></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.maskFull = false;

Get the maskFull property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let maskFull = maskedtextbox.maskFull;

maxLengthnumber

Specifies the upper limit on the number of characters that a user is allowed to input. If the user attempts to enter more characters than this limit, additional input will be prevented or ignored. This property is commonly used in form fields to enforce data length constraints and ensure consistent data entry.

Default value

5
Try a demo showcasing the maxLength property.

Example

Set the maxLength property. 

 <smart-masked-text-box max-length='120'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.maxLength = 150;

Get the maxLength property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let maxLength = maskedtextbox.maxLength;

messagesobject

Defines or retrieves an object containing customizable text strings used within the widget, allowing for localization of user interface elements. This property works in conjunction with the locale property to provide translations and adapt the widget's display language to different regions or languages. Use this to specify or override default labels, messages, or prompts shown in the widget.

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-masked-text-box messages='{"de":{"propertyUnknownType":"Die Eigenschaft '{{name}}' hat ein nicht definiertes 'type'-Member!","propertyInvalidValue":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualValue}}, Erwarteter Wert: {{value}}!","propertyInvalidValueType":"Ungultiger Eigenschaftswert '{{name}}'! Aktueller Wert: {{actualType}}, Erwarteter Wert: {{type}}!","elementNotInDOM":"Element existiert nicht in DOM! Bitte fugen Sie das Element zum DOM hinzu, bevor Sie eine Methode aufrufen.","moduleUndefined":"Modul ist nicht definiert.","missingReference":"{{elementType}}: Fehlender Verweis auf {{files}}.","htmlTemplateNotSuported":"{{elementType}}: Browser unterstutzt keine HTMLTemplate-Elemente.","invalidTemplate":"{{elementType}}: '{{property}}' Die Eigenschaft akzeptiert eine Zeichenfolge, die mit der ID eines HTMLTemplate-Elements aus dem DOM ubereinstimmen muss.","invalidNode":"{{elementType}}: Ungultiger Parameter '{{node}}' beim Aufruf von {{method}}."}}'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.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 maskedtextbox = document.querySelector('smart-masked-text-box');
 let messages = maskedtextbox.messages;

namestring

Sets or retrieves the value of the element's name attribute. The name attribute identifies the element within an HTML form, ensuring its value is included in the form data sent to the server upon submission. This is essential for correctly processing user input on the backend.

Default value

""

Example

Set the name property. 

 <smart-masked-text-box name='MaskedTextBox'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.name = 'textbox';

Get the name property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let name = maskedtextbox.name;

placeholderstring

Specifies the placeholder text displayed in the input field when both the value and mask properties are unset or empty. This text provides users with a hint or example of the expected input format until they enter a value.

Default value

""
Try a demo showcasing the placeholder property.

Example

Set the placeholder property. 

 <smart-masked-text-box placeholder='(650)303-6565'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.placeholder = '4147-9687-1385-6921';

Get the placeholder property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let placeholder = maskedtextbox.placeholder;

promptCharstring

Specifies the character used as the placeholder in the input mask for the element. This character indicates where user input is expected within the input field.

Default value

"_"
Try a demo showcasing the promptChar property.

Example

Set the promptChar property. 

 <smart-masked-text-box prompt-char='*'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.promptChar = '-';

Get the promptChar property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let promptChar = maskedtextbox.promptChar;

readonlyboolean

When the element is set to readonly, users can view its content but cannot modify or interact with it in any way. This ensures that the element’s value remains unchanged by user input, while still being visible on the page.

Default value

false

Example

Set the readonly property. 

 <smart-masked-text-box readonly></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.readonly = true;

Get the readonly property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let readonly = maskedtextbox.readonly;

rejectInputOnFirstFailureboolean

Specifies whether the parsing process should immediately halt upon encountering the first invalid character in the user input, or continue attempting to parse the remaining input.

Default value

false

Example

Set the rejectInputOnFirstFailure property. 

 <smart-masked-text-box reject-input-on-first-failure></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.rejectInputOnFirstFailure = false;

Get the rejectInputOnFirstFailure property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let rejectInputOnFirstFailure = maskedtextbox.rejectInputOnFirstFailure;

requiredboolean

Indicates that this input field is required and cannot be left empty; users must provide a value before the form can be successfully submitted.

Default value

false

Example

Set the required property. 

 <smart-masked-text-box required></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.required = false;

Get the required property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let required = maskedtextbox.required;

resetOnPromptboolean

Controls whether entering a character in the input field that matches the prompt character will reset the currently selected value. This setting is relevant only when allowPromptAsInput is enabled, meaning the prompt character can be used as user input. When enabled, if the user types the prompt character, the input’s selected value will be cleared; otherwise, the value remains unchanged.

Default value

false

Example

Set the resetOnPrompt property. 

 <smart-masked-text-box reset-on-prompt></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.resetOnPrompt = false;

Get the resetOnPrompt property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let resetOnPrompt = maskedtextbox.resetOnPrompt;

resetOnSpaceboolean

Specifies whether pressing the spacebar will clear the currently selected value in the input field. When set to true, pressing the space key will reset (clear) the selection; when set to false, the value remains unchanged.

Default value

false
Try a demo showcasing the resetOnSpace property.

Example

Set the resetOnSpace property. 

 <smart-masked-text-box reset-on-space></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.resetOnSpace = false;

Get the resetOnSpace property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let resetOnSpace = maskedtextbox.resetOnSpace;

rightToLeftboolean

Specifies or retrieves a Boolean value that determines whether the element’s content is aligned to support right-to-left (RTL) languages, such as Arabic or Hebrew. When set to true, the element’s text direction and alignment are adjusted to display content appropriately for RTL locales.

Default value

false
Try a demo showcasing the rightToLeft property.

Example

Set the rightToLeft property. 

 <smart-masked-text-box right-to-left></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.rightToLeft = false;

Get the rightToLeft property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let rightToLeft = maskedtextbox.rightToLeft;

selectAllOnFocusboolean

Determines if the entire value of the input field will be automatically highlighted (selected) when the input receives focus, allowing users to easily replace or copy the existing content.

Default value

false

Example

Set the selectAllOnFocus property. 

 <smart-masked-text-box select-all-on-focus></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.selectAllOnFocus = false;

Get the selectAllOnFocus property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let selectAllOnFocus = maskedtextbox.selectAllOnFocus;

textMaskFormat"excludePromptAndLiterals" | "includePrompt" | "includeLiterals" | "includePromptAndLiterals"

Specifies whether the value entered in the input field should include or exclude the static characters (prompts and literals) defined by the input mask. When enabled, the resulting value will contain these mask characters; otherwise, only the user input (without mask characters) will be stored.

Allowed Values

  • "excludePromptAndLiterals" - Excludes the prompt and literal characters from the mask.
  • "includePrompt" - Includes the prompt character from the mask along with the rest of the input.
  • "includeLiterals" - Includes all literal characters from the mask along with the input.
  • "includePromptAndLiterals" - Includes the prompt and literal characters from the mask along with the input.

Default value

"excludePromptAndLiterals"

Example

Set the textMaskFormat property. 

 <smart-masked-text-box text-mask-format='includePrompt'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.textMaskFormat = 'includeLiterals';

Get the textMaskFormat property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let textMaskFormat = maskedtextbox.textMaskFormat;

themestring

Specifies the visual theme to be applied. The theme controls the overall appearance—including colors, fonts, and style—of the element, ensuring a consistent and customizable look and feel.

Default value

""

Example

Set the theme property. 

 <smart-masked-text-box theme='blue'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.theme = 'red';

Get the theme property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let theme = maskedtextbox.theme;

unfocusableboolean

If this property is set to true, the element will be excluded from keyboard navigation and cannot receive focus, either by tabbing or programmatically.

Default value

false

Example

Set the unfocusable property. 

 <smart-masked-text-box unfocusable></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.unfocusable = false;

Get the unfocusable property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let unfocusable = maskedtextbox.unfocusable;

valuestring

Gets the current value of the element or sets a new value for the element, depending on how the method is used. When called without arguments, it returns the element's current value. When provided with a value as an argument, it updates the element with the specified value. Commonly used with form input elements.

Default value

""

Example

Set the value property. 

 <smart-masked-text-box value='Demo value.'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.value = 'New demo value.';

Get the value property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let value = maskedtextbox.value;

validationfunction | null



A callback function that enables you to define custom validation logic for the input value. This function receives the input value as an argument and should return a boolean value: return true if the value is considered valid, or false if it is invalid. If the function returns false, the input will be treated as invalid and may trigger corresponding validation error messages or prevent form submission. Use this to implement validations that go beyond the default rules.

Try a demo showcasing the validation property.

Example

Set the validation property. 

 <smart-masked-text-box validation='function(){ if(value.length === 5){ return true } return false }'></smart-masked-text-box>

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

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 maskedtextbox.validation = function(){ if(value.length < 10){ return true } return false };

Get the validation property. 

 const maskedtextbox = document.querySelector('smart-masked-text-box');
 let validation = maskedtextbox.validation;

Events

changeCustomEvent

This event is triggered whenever the user modifies the content of the Text Box, such as by typing, deleting, or pasting text. It fires each time the value of the Text Box changes, allowing you to respond to user input in real-time.

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

Arguments

evCustomEvent
ev.detailObject
ev.detail.oldValue - The previous value before it was changed.
ev.detail.value - The new value.

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 maskedtextbox = document.querySelector('smart-masked-text-box');
maskedtextbox.addEventListener('change', function (event) {
    const detail = event.detail,
        oldValue = detail.oldValue,
        value = detail.value;

	// event handling code goes here.
})

changingCustomEvent

This event is triggered whenever a key is released (on key up) in the MaskedTextBox control and the input value has been modified as a result. It only fires if the key up event causes a change in the current value of the MaskedTextBox, allowing you to respond specifically to user edits in real-time.

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

Arguments

evCustomEvent
ev.detailObject
ev.detail.oldValue - The previous value before it was changed.
ev.detail.value - The new value.

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 changing event. 

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

	// event handling code goes here.
})

validationCustomEvent

This event is triggered when the validation property is set. It indicates the result of the validation process—specifically, whether the validation completed successfully (true) or failed (false). Use this event to respond to changes in the validation state of the associated data or form.

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

Arguments

evCustomEvent
ev.detailObject
ev.detail.success - A flag inidicating whether the validation was successfull or not.

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 validation event. 

const maskedtextbox = document.querySelector('smart-masked-text-box');
maskedtextbox.addEventListener('validation', function (event) {
    const detail = event.detail,
        success = detail.success;

	// event handling code goes here.
})

Methods

focus(): void

Sets keyboard and screen reader focus to the specified element, making it the active element for user interactions such as typing or accessibility navigation.


Invoke the focus method.

const maskedtextbox = document.querySelector('smart-masked-text-box');
maskedtextbox.focus();

blur(): void

Applies a blur effect to the element, causing its content and any child elements to appear out of focus by softening edges and details. The degree of blur can typically be adjusted to achieve the desired level of visual obscurity.


Invoke the blur method.

const maskedtextbox = document.querySelector('smart-masked-text-box');
maskedtextbox.blur();

CSS Variables

--smart-masked-text-box-default-widthvar()

Default value

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

smartMasked default width

--smart-masked-text-box-default-heightvar()

Default value

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

smartMasked default height