@ngneat/input-mask
@ngneat/input-mask is an angular library that creates an input mask. Behind the scene, it uses inputmask.
Compatibility with Angular Versions
| @ngneat/input-mask | Angular |
|---|---|
| 4.x.x | >= 11.2.7 < 13 |
| 5.x.x | 13 |
| 6.x.x | 14 |
Features
- ๐ก Support for form validation
- ๐ญ Wrapper function to easily create input-masks
- ๐ Helps you to convert final values to desired format
- โ๏ธ Single directive to handle everything
- ๐ All the configurations of inputmask provided
Installation
Angular
You can install it through Angular CLI, which is recommended:
ng add @ngneat/input-maskor with npm
npm install @ngneat/input-mask inputmask@5
npm install -D @types/inputmask@5When you install using npm or yarn, you will also need to import InputMaskModule in your app.module:
import { InputMaskModule } from '@ngneat/input-mask';
@NgModule({
imports: [InputMaskModule],
})
class AppModule {}Config
There few configuration options available with InputMaskModule:
import { InputMaskModule } from '@ngneat/input-mask';
@NgModule({
imports: [InputMaskModule.forRoot({ inputSelector: 'input', isAsync: true })],
})
class AppModule {}| Option | Type | Description | Default Value |
|---|---|---|---|
inputSelector |
string |
CSS selector, which will be used with querySelector to get the native input from host element. This is useful when you want to apply input-mask to child <input> of your custom-component |
input |
isAsync |
boolean |
If set true, MutationObserver will be used to look for changes until it finds input with inputSelector |
false |
Usage examples
1. Date
import { Component } from '@angular/core';
import { FormControl } from '@angular/forms';
import { createMask } from '@ngneat/input-mask';
@Component({
selector: 'app-root',
template: `
<input
[inputMask]="dateInputMask"
[formControl]="dateFC"
placeholder="dd/mm/yyyy"
/>
`,
})
export class AppComponent {
dateInputMask = createMask<Date>({
alias: 'datetime',
inputFormat: 'dd/mm/yyyy',
parser: (value: string) => {
const values = value.split('/');
const year = +values[2];
const month = +values[1] - 1;
const date = +values[0];
return new Date(year, month, date);
},
});
dateFC = new FormControl('');
}2. IP Address
@Component({
template: `
<input
[inputMask]="ipAddressMask"
[formControl]="ipFC"
placeholder="_._._._"
/>
`,
})
export class AppComponent {
ipAddressMask = createMask({ alias: 'ip' });
ipFC = new FormControl('');
}3. Currency
@Component({
template: `
<input
[inputMask]="currencyInputMask"
[formControl]="currencyFC"
placeholder="$ 0.00"
/>
`,
})
export class AppComponent {
currencyInputMask = createMask({
alias: 'numeric',
groupSeparator: ',',
digits: 2,
digitsOptional: false,
prefix: '$ ',
placeholder: '0',
});
currencyFC = new FormControl('');
}4. License Plate
@Component({
template: `
<input
[inputMask]="licenseInputMask"
[formControl]="licenseFC"
placeholder="___-___"
/>
`,
})
export class AppComponent {
licenseInputMask = createMask('[9-]AAA-999');
licenseFC = new FormControl('');
}5. Email
@Component({
template: `
<input
[inputMask]="emailInputMask"
[formControl]="emailFC"
placeholder="_@_._"
/>
`,
})
export class AppComponent {
emailInputMask = createMask({ alias: 'email' });
emailFC = new FormControl('');
}6. Custom Component
If you have some component and you want to apply input-mask to the inner <input> element of that component, you can do that.
For example, let's assume you have a CustomInputComponent:
@Component({
selector: 'app-custom-input',
template: `
<input
[formControl]="formControl"
[inputMask]="inputMask"
[placeholder]="placeholder"
/>
`,
})
export class CustomInputComponent {
@Input() formControl!: FormControl;
@Input() inputMask!: InputmaskOptions<any>;
@Input() placeholder: string | undefined;
}And your AppComponent looks like this:
@Component({
selector: 'app-root',
template: `
<app-custom-input
[formControl]="dateFCCustom"
[inputMask]="dateInputMaskCustom"
placeholder="Date"
></app-custom-input>
`,
})
export class AppComponent {
dateInputMaskCustom = createMask<Date>({
alias: 'datetime',
inputFormat: 'dd/mm/yyyy',
parser: (value: string) => {
const values = value.split('/');
const year = +values[2];
const month = +values[1] - 1;
const date = +values[0];
return new Date(year, month, date);
},
});
dateFCCustom = new FormControl('');
}So to apply input-mask on CustomInputComponent, use configuration with InputMaskModule like below:
import { InputMaskModule } from '@ngneat/input-mask';
@NgModule({
imports: [
InputMaskModule.forRoot({
isAsync: false, // set to true if native input is lazy loaded
inputSelector: 'input',
}),
],
})
class AppModule {}More examples
All examples are available on stackblitz.
You can create any type of input-mask which is supported by InputMask plugin.
Validation
When [inputMask] is used with [formControl], it adds validation out-of-the box. The validation works based on isValid function.
If the validation fails, the form-control will have below error:
{ "inputMask": true }createMask wrapper function
This library uses inputmask plugin to handle mask related tasks. So, you can use all the options available there.
The recommended way to create an inputmask is to use the createMask function provided with this library.
parser function
Apart from inputmask options, we have added one more option called parser. This basically helps you to keep the value of form-control in pre-defined format, without updating UI.
For example, you want your users to enter date in input[type=text] with dd/mm/yyyy format and you want to store a Date value in the form-control:
@Component({
template: `
<input
[inputMask]="dateInputMask"
[formControl]="dateFC"
placeholder="dd/mm/yyyy"
/>
`,
})
export class AppComponent {
dateInputMask = createMask<Date>({
alias: 'datetime',
inputFormat: 'dd/mm/yyyy',
parser: (value: string) => {
const values = value.split('/');
const year = +values[2];
const month = +values[1] - 1;
const date = +values[0];
return new Date(year, month, date);
},
});
dateFC = new FormControl('');
}In above example, whenver you try to access dateFC.value, it won't be the string which user entered, but rather a Date created based on the parser function.
formatter function
Apart from the parser function, we have added one more option called formatter. This helps you if you want to change the format of a date you receive from the Database.
For example, you receive a date from your database in the format 'yyyy-MM-dd' but you want to display it 'dd/MM/yyyy'.
@Component({
template: `
<input
[inputMask]="dateInputMask"
[formControl]="dateFC"
placeholder="dd/mm/yyyy"
/>
`,
})
export class AppComponent {
dateInputMask = createMask<Date>({
alias: 'datetime',
inputFormat: 'dd/MM/yyyy',
formatter: (value: string) => {
const values = value.split('-');
const date = +values[2];
const month = +values[1] - 1;
const year = +values[0];
return formatDate(new Date(year, month, date), 'dd/MM/yyyy', 'en-US');
},
});
dateFC = new FormControl('1990-12-28');
}Contributors โจ
Thanks goes to these wonderful people (emoji key):
 Dharmen Shah ๐ป ๐ ๐ ๐ก ๐ง ๐ฆ |
 Netanel Basal ๐ ๐ผ ๐ค ๐งโ๐ซ ๐ ๐ |
 Robin Herbots ๐ค |
 P. Zontrop ๐ฆ |
 Artur Androsovych ๐ง |
 Pawel Boguslawski ๐ง |
This project follows the all-contributors specification. Contributions of any kind welcome!!
![allcontributors[bot] avatar](https://avatars.githubusercontent.com/in/23186?v=4 "allcontributors[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent