All Components
Components

Components / Inputs / MaskedTextBox

MaskedTextBox Overview

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

Basic Usage

The following example demonstrates the MaskedTextBox in action.

@Component({
    selector: 'my-app',
    template: `
        <p>Enter phone number</p>
        <kendo-maskedtextbox [mask]="mask" [value]="value"></kendo-maskedtextbox>
    `
})

class AppComponent {
    public value: string = "359884123321";
    public mask: string = "(999) 000-00-00-00";
}

Features

The MaskedTextBox delivers the following features:

Value

The MaskedTextBox enables you to format its masked (visible) value by setting value.

The configuration is based on the following properties:

  • mask—The current mask pattern of the component.
  • prompt—The character used for the unfilled parts of the mask.

As a result, the masked value is formatted when the user interacts with the component by pasting or typing in the input field. The value property is recomputed and uses the following configuration:

  • promptPlaceholder—The character you can use to replace the prompt character from the masked value in the value. By default, it is an empty string. The default approach facilitates the persisting of the unfilled parts of the mask in the extracted value.
  • includeLiterals—The property that indicates whether to include literals in the value of the component. By default, includeLiterals does not include literals.

The formatting of the MaskedTextBox value triggers the valueChange event.

@Component({
    selector: 'my-app',
    template: `
        <div class="example-config">
            <input id="ac" type="checkbox" [(ngModel)]="includeLiterals">
            <label for="ac">Include literals in the value</label>
        </div>
        <div class="example-wrapper">
            <kendo-maskedtextbox
              [includeLiterals]="includeLiterals"
              [(value)]="value"
              [mask]="mask">
            </kendo-maskedtextbox>
            Component value: {{value}}
        </div>
    `
})

class AppComponent {
    public includeLiterals: boolean = false;
    public value: string = "5748157000194334";
    public mask: string = "0000-0000-0000-0000";
}

Masks

The MaskedTextBox supports the following built-in mask rules:

  • 0—Requires a digit (0-9).
  • 9—Requires a digit (0-9) or a space.
  • #—Requires a digit (0-9), space, plus (+), or minus (-) sign.
  • L—Requires a letter (a-Z).
  • ?—Requires a letter (a-Z) or a space.
  • A—Requires an alphanumeric (0-9, a-Z).
  • a—Requires an alphanumeric (0-9, a-Z) or a space.
  • &—Requires a character (excluding space).
  • C—Requires a character or a space.

You can also define custom rules by using the rules property.

Apart from the built-in and customs rules, you can also use static symbols in the mask pattern that are also known as literals. In the masked value, a literal is always rendered on the same position as the position it is defined in the mask property.

To escape a mask rule, use the \ character. An escaped rule turns into a literal.

The following example demonstrates how to use the digit-requiring mask (0) and literal (-) of the MaskedTextBox.

@Component({
    selector: 'my-app',
    template: `
        <kendo-maskedtextbox
          [value]="value"
          [mask]="mask">
        </kendo-maskedtextbox>
    `
})

class AppComponent {
    public value: string = "5748-1570-0019-4334";
    public mask: string = "0000-0000-0000-0000";
}

The following example demonstrates how to extend the available mask rules.

@Component({
    selector: 'my-app',
    template: `
        <div class="example-config">
            <p>{{ mask }}</p>
            <ul>
                <li>Y - cyrillic only</li>
                <li>L - latin only</li>
            </ul>
        </div>
        <kendo-maskedtextbox
          [value]="value"
          [mask]="mask"
          [rules]="rules">
        </kendo-maskedtextbox>
    `
})

class AppComponent {
    public value: string = "абвг abcd";
    public mask: string = "YYYY LLLL";
    public rules: { [key: string]: RegExp } = {
        "L": /[a-zA-Z]/,
        "Y": /[\u0400-\u0481\u048A-\u04FF]/
    };
}

Disabled User Interaction

The MaskedTextBox allows you to fully disable user interaction with the component. By default, the MaskedTextBox is enabled and the disabled property is set to false.

@Component({
    selector: 'my-app',
    template: `
        <kendo-maskedtextbox
          [value]="value"
          [mask]="mask"
          [disabled]="disabled"
        ></kendo-maskedtextbox>
    `
})

class AppComponent {
    public value: string = "Andrew Green";
    public mask: string = "aaaaaaaaaaaaaaaaa";
    public disabled: boolean = true;
}

For detailed information on the configuration of the MaskedTextBox, refer to its client-side API documentation.

Validation

The MaskedTextBox features a built-in mask validator. It ensures that the user submits a valid input. The validator is enabled by default. To turn it off, set the maskValidation property to false.

@Component({
    selector: 'my-app',
    template: `
        <form #templateForm="ngForm" novalidate>
            <p>Enter valid postcode (A9 9AA)</p>
            <kendo-maskedtextbox
                name="value1"
                [(ngModel)]="value"
                [mask]="mask"
                [maskValidation]="maskValidation"
            ></kendo-maskedtextbox>
            <button [disabled]="!templateForm.valid" type="submit" class="k-button">Submit</button>
        </form>
    `
})

class AppComponent {
    public value: string = "M1 1AE";
    public mask: string = "A9 9AA";
    public maskValidation: boolean = true;
}

Forms Support

It is possible to use the MaskedTextBox in reactive and template-driven forms.

Template-Driven Forms

The template-driven forms enable you to bind the value of the MaskedTextBox to the forms model by using the ngModel directive.

The following example demonstrates how to use the MaskedTextBox in a template-driven form.

@Component({
    selector: 'my-app',
    template: `
        <form #form="ngForm">
            <div class="example-config">
                <strong>{{ value | json }}</strong>
            </div>
            <label>
            Select Gender:
                <kendo-maskedtextbox
                name="masked"
                [mask]="'??????????'"
                [(ngModel)]="value"
            >
            </kendo-maskedtextbox> <br />
            </label>
        </form>
    `
   })
export class AppComponent {}

Reactive Forms

The FormGroup provides a way to render reactive forms. For more details, refer to the Angular Documentation.

The following example demonstrates how to use the MaskedTextBox in a reactive form.

import {
       FormsModule,
       ReactiveFormsModule,
       FormGroup,
       FormBuilder
   } from '@angular/forms';

   @Component({
       selector: 'my-app',
       template: `
           <div class="example-config">
               Question mark (?) is a placeholder for a letter or a space.
           </div>
           <form [formGroup]="form" #reactiveForm="ngForm">
               <kendo-maskedtextbox formControlName="masked" [mask]="'??????????'"></kendo-maskedtextbox> <br />
               <p *ngIf="form.controls.masked.errors">{{form.controls.masked.errors | json}}</p>
           </form>
       `
   })
   class AppComponent {
       public form: FormGroup;
       constructor(private formBuilder: FormBuilder) {
           this.form = this.formBuilder.group({
               masked: ["John"]
           });
       }
   }
In this article