MaskedTextBox — Smart UI JavaScript API

MaskedTextBox — Smart UI JavaScript API

On this page + Quick start

Quick start · JavaScript

Complete starter source per framework. Run the scaffold/install command first, then replace the listed files with the full code below.

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1" />
  <title>MaskedTextBox - JavaScript Quick Start</title>
  <link rel="stylesheet" href="./node_modules/smart-webcomponents/source/styles/smart.default.css" />
</head>
<body>
  <smart-masked-text-box id="demo-maskedtextbox"></smart-masked-text-box>

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

    const el = document.getElementById('demo-maskedtextbox');
    if (el) {
      el.placeholder = 'Type here...';
      el.mask = '#### #### #### ####';
      el.placeholder = '____ ____ ____ ____';

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

Developer Quick Reference

Component: MaskedTextBox   Framework: JavaScript   Selector: smart-masked-text-box

API counts: 35 properties, 2 methods, 3 events

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

Common methods: focus(), blur()

Common events: change, changing, validation

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

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

Class

MaskedTextBox

MaskedTextBox

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

Selector

smart-masked-text-box

Quick picks

changedisabledfocusvalue

Properties

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.
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.
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.
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.
UunlockKeyDefines or retrieves the unlockKey, a unique identifier or code required to activate and access the product's full features.
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.
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.

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

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.
FfocusSets keyboard and screen reader focus to the specified element, making it the active element for user interactions such as typing or accessibility navigation.

Properties

allowPromptAsInputChecks 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.boolean

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

Examples

Markup and runtime examples for allowPromptAsInput:

HTML attribute:

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

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

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

Read the current value:

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

animationSpecifies 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."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"

Examples

Markup and runtime examples for animation:

HTML:

<smart-masked-text-box animation="none"></smart-masked-text-box>

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

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

Read the current value:

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

asciiOnlySpecifies 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.boolean

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

Examples

Markup and runtime examples for asciiOnly:

HTML attribute:

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

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

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

Read the current value:

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

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

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

Examples

Markup and runtime examples for autoFocus:

HTML attribute:

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

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

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

Read the current value:

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

autoShowMaskControls 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.boolean

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

Examples

Markup and runtime examples for autoShowMask:

HTML attribute:

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

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

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

Read the current value:

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

cutCopyMaskFormatSpecifies 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."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.

Examples

Markup and runtime examples for cutCopyMaskFormat:

HTML:

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

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

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

Read the current value:

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

disabledDetermines 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.boolean

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

Examples

Markup and runtime examples for disabled:

HTML attribute:

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

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

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

Read the current value:

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

enterKeyBehaviorDefines 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"."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"

Examples

Markup and runtime examples for enterKeyBehavior:

HTML:

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

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

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

Read the current value:

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

hidePromptOnLeaveControls 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.boolean

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.

Examples

Markup and runtime examples for hidePromptOnLeave:

HTML attribute:

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

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

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

Read the current value:

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

hintDisplays 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.string

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.

Examples

Markup and runtime examples for hint:

HTML:

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

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

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

Read the current value:

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

isOverwriteModeSpecifies 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.boolean

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.

Examples

Markup and runtime examples for isOverwriteMode:

HTML attribute:

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

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

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

Read the current value:

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

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

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.

Examples

Markup and runtime examples for label:

HTML:

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

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

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

Read the current value:

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

localeSpecifies 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.string

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"

Examples

Markup and runtime examples for locale:

HTML:

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

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

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

Read the current value:

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

localizeFormatFunctionA 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.function | 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.

Examples

Markup and runtime examples for localizeFormatFunction:

HTML:

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

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

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

Read the current value:

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

maskSpecifies 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.string

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.

Examples

Markup and runtime examples for mask:

HTML:

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

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

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

Read the current value:

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

maskCompletedSpecifies 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.boolean

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

Examples

Markup and runtime examples for maskCompleted:

HTML attribute:

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

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

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

Read the current value:

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

maskFullSpecifies 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.boolean

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

Examples

Markup and runtime examples for maskFull:

HTML attribute:

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

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

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

Read the current value:

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

maxLengthSpecifies 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.number

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.

Examples

Markup and runtime examples for maxLength:

HTML:

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

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

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

Read the current value:

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

messagesDefines 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.object

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

}

Examples

Markup and runtime examples for messages:

HTML:

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

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

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

Read the current value:

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

nameSets 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.string

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

""

Examples

Markup and runtime examples for name:

HTML:

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

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

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

Read the current value:

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

placeholderSpecifies 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.string

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.

Examples

Markup and runtime examples for placeholder:

HTML:

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

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

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

Read the current value:

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

promptCharSpecifies 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.string

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.

Examples

Markup and runtime examples for promptChar:

HTML:

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

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

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

Read the current value:

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

readonlyWhen 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.boolean

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

Examples

Markup and runtime examples for readonly:

HTML attribute:

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

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

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

Read the current value:

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

rejectInputOnFirstFailureSpecifies 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.boolean

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

Examples

Markup and runtime examples for rejectInputOnFirstFailure:

HTML attribute:

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

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

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

Read the current value:

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

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

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

Examples

Markup and runtime examples for required:

HTML attribute:

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

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

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

Read the current value:

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

resetOnPromptControls 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.boolean

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

Examples

Markup and runtime examples for resetOnPrompt:

HTML attribute:

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

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

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

Read the current value:

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

resetOnSpaceSpecifies 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.boolean

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.

Examples

Markup and runtime examples for resetOnSpace:

HTML attribute:

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

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

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

Read the current value:

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

rightToLeftSpecifies 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.boolean

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.

Examples

Markup and runtime examples for rightToLeft:

HTML attribute:

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

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

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

Read the current value:

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

selectAllOnFocusDetermines 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.boolean

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

Examples

Markup and runtime examples for selectAllOnFocus:

HTML attribute:

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

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

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

Read the current value:

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

textMaskFormatSpecifies 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."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"

Examples

Markup and runtime examples for textMaskFormat:

HTML:

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

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

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

Read the current value:

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

themeSpecifies 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.string

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

""

Examples

Markup and runtime examples for theme:

HTML:

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

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

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

Read the current value:

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

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

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

Examples

Markup and runtime examples for unfocusable:

HTML attribute:

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

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

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

Read the current value:

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

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

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

Default value

""

Examples

Markup and runtime examples for unlockKey:

HTML:

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

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

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

Read the current value:

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

validationA 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.function | 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.

Examples

Markup and runtime examples for validation:

HTML:

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

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

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

Read the current value:

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

valueGets 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.string

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

""
Try a demo showcasing the value property.

Examples

Markup and runtime examples for value:

HTML:

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

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

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

Read the current value:

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

Events

changeThis 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.CustomEvent

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.

Try a demo showcasing the change event.

Examples

Listen for change using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

document.querySelector('smart-masked-text-box')?.addEventListener('change', (event) => {
    const detail = event.detail,
        oldValue = detail.oldValue,
        value = detail.value;

	// event handling code goes here.
})

changingThis 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.CustomEvent

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.

Examples

Listen for changing using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

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

	// event handling code goes here.
})

validationThis 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.CustomEvent

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.

Try a demo showcasing the validation event.

Examples

Listen for validation using the pattern that matches your stack.

DOM — listen on the custom element (use a specific selector if the page has more than one):

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

	// event handling code goes here.
})

Methods

blur(): voidApplies 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.

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.

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

document.querySelector('smart-masked-text-box')?.blur();

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

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

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

document.querySelector('smart-masked-text-box')?.focus();

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