Skip to content

Mask Directive Specification

Boris Penkov edited this page Nov 22, 2022 · 7 revisions

igxMask Directive Specification


IgxMask directive should provide means for controlling user input and formatting the visible value based on a configurable mask rules.


As a developer I want to be able to apply a mask on an input field so that the user can only type a predetermined pattern.

<input type="text" igxInput [igxMask]="myMask"/>

The following built-in mask rules should be supported:

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

Static symbols (literals) in the mask pattern should also be supported.

As a developer I want to be able specify the character used for the unfilled parts of the mask (prompt char).

As a developer I want to be able to either include the mask literals in the underlying component value, or preserve its row value.

As a developer I want to be able to implement custom logic when the input value changes while the user interacts with the component.

End user

The 'masked' value is formatted when the user interacts with the component by pasting, deleting or typing in the input field.

End User Experience

User input is masked.

Developer Experience

Use the directive on an input element.

<input type="text" igxInput [value]="1234567890" [igxMask]="'(000) 0000-000'"/>

Include mask literals in the the underlying component value.

public myValue = "1234567890";
public myMask = "(000) 0000-000";

<input type="text" igxInput [(ngModel)]="myValue" [igxMask]="myMask" [includeLiterals]="true"/>

Exclude mask literals from the the underlying component value.

public myValue = "1234567890";
public myMask = "(000) 0000-000";

<input type="text" igxInput [(ngModel)]="myValue" [igxMask]="myMask" [includeLiterals]="false"/>

Implement custom logic when the value changes

myValue = "1234567890";
myMask = "(000) 0000-000";
raw: string;
formatted: string;

handleValueChange(event) {
  this.raw = event.rawValue;
  this.formatted = event.formattedValue;

<input type="text" igxInput [(ngModel)]="myValue" [igxMask]="myMask" (onValueChange)="handleValueChange($event)"/>

<div>Row value: {{raw}}</div>
<div>Formatted value: {{formatted}}</div>



Name Description
mask Represents the current mask
promptChar Placeholder character representing a fillable spot in the mask (default is underscore)
includeLiterals Indicates whether to include literals in the raw value


Name Description
onValueChange Fires each time the value changes
  • If the igxTextSelection directive is applied to the input where the igxMask directive is also applied, dropping text on the input will always put the text at the front of the mask, no matter if there have been any prior interactions with it. This is because the igxTextSelection directive will trigger select on the nativeElement of the input which will mess up its selectionStart & selectionEnd properties. The select is triggered upon focus which occurs right after drop. Currently, the issue is present on Chromium as they clear the input on drop. Firefox does not behave like this - it does not clear the mask when dropping, so this behavior does not occur. Additionally, if the igxTextSelection directive is not applied, drop actions behave normally on all browsers.
Clone this wiki locally