MaskedTextBox Overview

The Kendo UI MaskedTextBox widget enables a controlled text input that is based on a specific format.

This specific format can be defined by using the mask option of the widget. Each mask can contain mask rules and mask literals. The mask literals are automatically entered for the user and cannot be removed.

The widget also has predefined rules which specify:

• Required or optional digit input.
• Required or optional letter input.
• Required or optional character input (allows any character).

For more information on its methods and configuration options, review the API Reference of the MaskedTextBox.

Getting Started

Initialize the MaskedTextBox

To initialize the MaskedTextBox, use the following example.

<input id="maskedtextbox" />
<script>
    $(document).ready(function(){
        $("#maskedtextbox").kendoMaskedTextBox({
            mask: "000000"
        });
    });
</script>

When a MaskedTextBox is initialized, it decorates the <input> element with a k-textbox CSS class.

Important

The default mask is an empty string which allows any input. To restrict user input, define a mask value.

Configuration

The MaskedTextBox provides configuration options that can be set during initialization. The available properties are:

• Value of the widget
• Mask value
• Custom mask rules
• Prompt char
• Culture name

For more information on its methods and configuration options, review the API Reference of the MaskedTextBox.

Rules

The following mask rules are available and predefined:

• 0—Digit. Accepts any digit between 0 and 9.
• 9—Digit or space. Accepts any digit between 0 and 9 or space.
• #—Digit or space. Identical to Rule 9. In addition, allows the + (plus) and - (minus) signs.
• L—Letter. Restricts the input to a-z and A-Z letters. This rule is equivalent to [a-zA-Z] in regular expressions.
• ?—Letter or space. Restricts the input to letters a-z and A-Z. This rule is equivalent to [a-zA-Z]|\s in regular expressions.
• &—Character. Accepts any character except a space. The rule is equivalent to \S in regular expressions.
• C—Character or space. Accepts any character. The rule is equivalent to . in regular expressions.
• A—Alphanumeric. Accepts letters and digits only.
• a—Alphanumeric or space. Accepts only letters, digits, and space.

Important

You can escape any of the masks by using the \ character. The escaped rules turn into literals.

Literals

Based on the current culture, the following mask literals are globalized:

• .—Decimal placeholder. The decimal separator is set according to the current culture used by Kendo UI.
• ,—Thousands placeholder. The display character is set according to the current culture used by Kendo UI.
• $—Currency symbol. The display character is set according to the current culture used by Kendo UI.

Important

You can escape any of the literals by using the \ character.

Customize Mask Rules

The MaskedTextBox enables you to define custom mask rules during initialization. To customize a mask rule, define it in the rules option. The widget supports rules defined as regular expression or a function.

Example

<input id="maskedtextbox">

<script>
  $(document).ready(function(){
    $("#maskedtextbox").kendoMaskedTextBox({
      mask: "~^",
      rules: {
        "~": /[+-]/,
        "^": function (char) {
          return char === "^"; //allow ony "^" symbol
        }
      }
    });
  });
</script>

Important

You can escape any of the predefined rules by using the rules option.

Known Limitations

Mobile Editing

To restrict the typed value, the MaskedTextBox listens to input events such as keydown and keypress.

Important

• In some mobile browsers, mostly Android or the Windows Mobile OS built-in browsers, those events do not trigger at all. This prevents the normal behavior of the MaskedTextBox because they are fundamental for the typing restriction.
• Recent tests show that the MaskedTextBox works in the latest iOS OS version.

You cannot work around these issues, because no other reliable way to detect typing in mobile browsers exist—virtual keyboard does not raise any other specific events.

See Also

• How to Customize Masks through MVVM Binding
• How to Show Custom Placeholder on Blur
• How to Use Custom Directive to Set Model Value
• How to Use Custom MVVM Binding to Set Model Value
• Overview of the ASP.NET MVC HtmlHelper Extension for the MaskedTextBox Widget
• Overview of the MaskedTextBox JSP Tag
• Overview of the MaskedTextBox PHP Class
• JavaScript API Reference