ngx-mask

A powerful Angular directive for input masking with customizable patterns

ngx-mask is the input-masking library built for modern Angular. One standalone directive (NgxMaskDirective) and pipe (NgxMaskPipe) cover all three form models — Reactive Forms, template-driven, and the new Signal Forms — through a first-class ControlValueAccessor, and run cleanly in zoneless and SSR applications. You get production-ready masks out of the box: dates and times with validity checking, numbers with thousand separators and decimal precision, IP, CPF/CNPJ, secure/hidden input, plus fully custom patterns with prefixes, suffixes and multi-mask expressions. No runtime dependencies beyond Angular, ~15 KB gzipped — provide it once, bind mask, done.

Table of Contents

• Features
• Demo
• Installation
• Version Compatibility
• Quick Start
  • Standalone Applications
  • NgModule-based Applications
• Contributing

Features

NGX-MASK is a feature-rich input mask directive for Angular applications that provides:

🎯 Masking Patterns • Custom patterns & expressions • Multiple mask patterns (|) • Built-in common patterns • Prefix & suffix support	🔢 Number Formatting • Thousand separators • Decimal markers • Negative numbers • Leading zeros	⚡ Input Control • Real-time validation • Clear on non-match • Show/hide mask typing • Keep character positions
📠Date & Time • Leading zero handling • AM/PM support • Custom separators • Multiple formats	🛠️ Customization • Custom placeholders • Special characters • Transform functions • Custom validation	📋 Form Integration • Reactive Forms • ControlValueAccessor • Built-in validation • Standalone support

Demo

Check out our live documentation and examples

Installation

# For Angular 17 and above
$ npm install ngx-mask    # Using npm
$ bun add ngx-mask       # Using bun

# For specific Angular versions:
# Angular 16.x.x
$ npm install ngx-mask@16.4.2    # Using npm
$ bun add ngx-mask@16.4.2       # Using bun

# Angular 15.x.x
$ npm install ngx-mask@15.2.3    # Using npm
$ bun add ngx-mask@15.2.3       # Using bun

# Angular 14.x.x
$ npm install ngx-mask@14.3.3    # Using npm
$ bun add ngx-mask@14.3.3       # Using bun

# Angular 13.x.x or 12.x.x
$ npm install ngx-mask@13.2.2    # Using npm
$ bun add ngx-mask@13.2.2       # Using bun

Package Manager Note: You can use either npm or bun based on your preference. Both package managers will work equally well with ngx-mask.

Version Compatibility

NGX-MASK follows Angular's official support policy, supporting Active and LTS versions. Currently supported:

• Angular 17 and newer (latest features and updates)
• For older Angular versions, use the corresponding NGX-MASK version as specified above

Note: Versions for Angular older than v17 will not receive new features or updates.

Quick Start

ngx-mask ships as a standalone directive (NgxMaskDirective) and pipe (NgxMaskPipe) — there is no NgxMaskModule in current versions. Configuration is registered through one of two provider functions:

• provideEnvironmentNgxMask(config?) — application-wide config. Use it once in bootstrapApplication / app.config.ts (or a root NgModule's providers).
• provideNgxMask(config?) — injector-level config. Use it in a component's or feature's providers to configure/override the options for that subtree only.

Directive inputs (e.g. [thousandSeparator]) always override any provider config. See USAGE.md for the full decision guide, examples, and common pitfalls.

Standalone Applications

Application-wide Setup with Default Config

bootstrapApplication(AppComponent, { providers: [provideEnvironmentNgxMask()] }).catch((err) =>
    console.error(err)
);

With Custom Configuration

import { NgxMaskConfig } from 'ngx-mask';

const maskConfig: Partial<NgxMaskConfig> = { validation: false };

bootstrapApplication(AppComponent, { providers: [provideEnvironmentNgxMask(maskConfig)] }).catch(
    (err) => console.error(err)
);

Feature-level Configuration

@Component({
    selector: 'my-feature',
    standalone: true,
    imports: [NgxMaskDirective],
    providers: [provideNgxMask()],
})
export class MyFeatureComponent {}

NgModule-based Applications

Module-based apps import the standalone directive/pipe into imports and register the provider function:

import { NgxMaskDirective, NgxMaskPipe, provideEnvironmentNgxMask } from 'ngx-mask';

@NgModule({
    imports: [NgxMaskDirective, NgxMaskPipe],
    exports: [NgxMaskDirective, NgxMaskPipe],
    providers: [provideEnvironmentNgxMask()],
})
export class AppModule {}

Migrating from ngx-mask ≤ 14 (NgxMaskModule)

NgxMaskModule.forRoot() / forChild() only exist in ngx-mask 14.x and older (Angular < 15):

// Before (ngx-mask <= 14)
@NgModule({ imports: [NgxMaskModule.forRoot(maskConfig)] })
export class AppModule {}

// After (current ngx-mask)
@NgModule({
    imports: [NgxMaskDirective],
    providers: [provideEnvironmentNgxMask(maskConfig)],
})
export class AppModule {}

Contributing

We welcome contributions! Please read our contributing guidelines to learn about our development process and how you can propose bugfixes and improvements.

---

Maintained by Igor Nepipenko