Angular Mask Directive Overview

    By applying the igxMask directive on a text input field, the developer can control user input and format the visible value, based on configurable mask rules. It provides different input options and ease in use and configuration.

    Angular Mask Example

    EXAMPLE

    Like this sample? Get access to our complete Ignite UI for Angular toolkit and start building your own apps in minutes. Download it for free.

    Getting Started with Ignite UI for Angular Mask

    To get started with the Ignite UI for Angular Mask directive, first you need to install Ignite UI for Angular. In an existing Angular application, type the following command:

    ng add igniteui-angular
    cmd

    For a complete introduction to the Ignite UI for Angular, read the getting started topic.

    The next step is to import the IgxMaskModule and IgxInputGroupModule in your app.module.ts file.

    igxMask directive is used on an input of type text.

    // app.module.ts
    
    ...
    import { IgxMaskModule, IgxInputGroupModule } from 'igniteui-angular';
    // import { IgxMaskModule, IgxInputGroupModule } from '@infragistics/igniteui-angular'; for licensed package
    
    @NgModule({
        ...
        imports: [..., IgxMaskModule, IgxInputGroupModule],
        ...
    })
    export class AppModule {}
    typescript

    Alternatively, as of 16.0.0 you can import the IgxMaskDirective as a standalone dependency.

    // home.component.ts
    
    import { IgxMaskDirective, IGX_INPUT_GROUP_DIRECTIVES } from 'igniteui-angular';
    // import { IgxMaskDirective, IGX_INPUT_GROUP_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package
    
    @Component({
        selector: 'app-home',
        template: `
        <igx-input-group>
            <igx-prefix>
                <igx-icon>phone</igx-icon>
            </igx-prefix>
            <label igxLabel>Phone</label>
            <input igxInput type="text" [igxMask]="'(####) 00-00-00 Ext. 9999'"/>
        </igx-input-group>
        `,
        styleUrls: ['home.component.scss'],
        standalone: true,
        imports: [IgxMaskDirective, IGX_INPUT_GROUP_DIRECTIVES]
    })
    export class HomeComponent {}
    typescript

    Now that you have the Ignite UI for Angular Mask module or directive imported, you can start using the igxMask directive.

    Using the Angular Mask

    Supported Built-in Mask Rules

    Mask Character Description
    0 requires a digit (0-9)
    9 requires a digit (0-9) or a space
    # requires a digit (0-9), 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
    & any keyboard character (excluding space)
    C any keyboard character

    Apply Mask on Input

    In the following example, we apply a phone number with an extension mask to an input.

    <!--sample.component.html-->
    
    <igx-input-group>
        <igx-prefix>
            <igx-icon>phone</igx-icon>
        </igx-prefix>
        <label igxLabel>Phone</label>
        <input igxInput type="text" [igxMask]="'(####) 00-00-00 Ext. 9999'"/>
    </igx-input-group>
    html

    If configured properly, you should see the demo sample in your browser.

    The IgxMaskDirective supports IME input and updates the mask when composition ends.

    Bind to Formatted/Raw Value

    Use the includeLiterals input to configure which input value (formatted or raw) to bind in your form when a specific mask is applied. By default, includeLiterals is set to false and the raw value is used.

    <!--sample.component.html-->
    
    <igx-switch [(ngModel)]="includeLiterals" (change)="clear()">
        Include Literals
    </igx-switch>
    
    <igx-input-group>
        <label igxLabel>
            Social Security Number
        </label>
        <input #ssn name="socialSecurityNumber" type="text"
            igxInput
            [igxMask]="'###-##-####'"
            [(ngModel)]="socialSecurityNumber"
            [includeLiterals]="includeLiterals" />
    </igx-input-group>
    
    <p *ngIf="socialSecurityNumber.length > 0">Value: {{ socialSecurityNumber }}</p>
    html
    // sample.component.ts
    
    public socialSecurityNumber: string = '123-45-6789';
    public includeLiterals: boolean = true;
    
    public clear() {
        if (this.includeLiterals === false){
            this.socialSecurityNumber = '123-45-6789';
        } else {
            this.socialSecurityNumber = '';
        }
    }
    typescript

    EXAMPLE

    Validate Masked Values

    In addition to setting a mask to an input, you can validate the entered value as well. The following example implements masks, validation and notification for invalid data using the Mask directive and Snack Bar component.

    <!--sample.component.html-->
    
    <igx-input-group>
        <label igxLabel for="birthday">Birthday</label>
        <input igxInput #dateInput [igxMask]="'00/00/0000'" [igxTextSelection]="true" name="birthday" type="text"
            (blur)="validateDate(dateInput, snackbar)" />
    </igx-input-group>
    
    <igx-snackbar #snackbar></igx-snackbar>
    html
    // sample.component.ts
    
    public validateDate(dateInput, snackbar) {
        if (!this.isDateValid(dateInput.value)) {
            this.notify(snackbar, 'Invalid Date', dateInput);
        }
    }
    
    private isDateValid(date) {
        return (new Date(date).toLocaleString() !== 'Invalid Date');
    }
    
    private notify(snackbar, message, input) {
        snackbar.message = message;
        snackbar.show();
    }
    typescript

    EXAMPLE

    Text Selection

    You can force the component to select all of the input text on focus using igxTextSelection. Find more info on igxTextSelection at Label & Input.

    Import the IgxTextSelectionModule in your app.module.ts file:

    ...
    import { ..., IgxTextSelectionModule } from 'igniteui-angular';
    // import { ..., IgxTextSelectionModule } from '@infragistics/igniteui-angular'; for licensed package
    
    @NgModule({
        ...
        imports: [..., IgxTextSelectionModule]
        ...
    })
    export class AppModule {}
    typescript

    Then add this to the template:

    <igx-input-group>
        <input igxInput [igxMask]="'###-##-####'" [igxTextSelection]="true"/>
    </igx-input-group>
    html

    You can see how this works in the previous sample.

    In order for the component to work properly, it is crucial to set igxTextSelection after the igxMask directive. The reason for this is both directives operate on the input focus event so text selection should happen after the mask is set.

    Apply additional formatting on focus and blur

    In addition to the default mask behavior, the user can implement his own custom pipes and take advantage of the focusedValuePipe and displayValuePipe input properties, to transform the value to a desired output when the input gets or loses focus. This will not affect the underlying model value. Let's demonstrate how this can be achieved!

    Implement two pipes that will append/remove a '%' sign at the end of the displayed value:

    @Pipe({ name: 'displayFormat' })
    export class DisplayFormatPipe implements PipeTransform {
        public transform(value: any): string {
            if (value !== null && value !== undefined) {
                value = value.toString().trim();
                if (!value.endsWith('%')) {
                    value += ' %';
                }
            }
            return value;
        }
    }
    
    @Pipe({ name: 'inputFormat' })
    export class InputFormatPipe implements PipeTransform {
        public transform(value: any): string {
            if (value !== null && value !== undefined) {
                value = value.toString().replace(/%/g, '').trim();
            }
            return value;
        }
    }
    typescript

    Pass an instance of each pipe to the focusedValuePipe and displayValuePipe input properties as follows:

    public value = 100;
    public displayFormat = new DisplayFormatPipe();
    public inputFormat = new InputFormatPipe();
    typescript
    <igx-input-group>
        <label igxLabel>Increase</label>
        <input
            igxInput
            type="text"
            [(ngModel)]="value"
            [igxMask]="'000'"
            [igxTextSelection]="true"
            [focusedValuePipe]="inputFormat"
            [displayValuePipe]="displayFormat"
        />
    </igx-input-group>
    html

    As a result, a '%' sign should be appended to the value on blur (i.e. when the user clicks outside the input) and will be removed once the input gets focus!

    EXAMPLE

    Adding a placeholder

    The user can also take advantage of the placeholder input property, which serves the purpose of the native input placeholder attribute. If no value is provided for the placeholder, the value set for the mask is used.

    value = null;
    typescript
    <igx-input-group>
        <label igxLabel>Date</label>
        <input igxInput
        type="text"
        [(ngModel)]="value"
        [igxMask]="'00/00/0000'"
        [placeholder]="'dd/mm/yyyy'"/>
    </igx-input-group>
    html

    EXAMPLE

    API References

    App Builder | CTA Banner

    Additional Resources

    Our community is active and always welcoming to new ideas.