br-masker

Brazilian input masks for Angular 20+.
A modern replacement for the deprecated br-mask library.

This library provides a standalone directive and a service for applying common Brazilian masks such as CPF, CNPJ, phone numbers, money, percent, thousand separators, and custom patterns.

Installation

npm install br-angular-masker

Supported Versions

| Technology | Supported | |-----------|-----------| | Angular | 20 and higher | | Ionic | 7, 8 | | Node.js | 18, 20, 22 | | Forms | Reactive Forms & Template-driven | | Architecture | Standalone Components |

Angular versions below 20 are not supported.

Features

• Standalone directive ([brMasker])
• CPF / CNPJ auto-detection
• Phone masks (with or without DDD)
• Money and percent formatting
• Thousand separators
• Custom masks (00:00, 999-999)
• Programmatic API (service)
• No jQuery
• No NgModules
• Tree-shakeable

Quick Start

Standalone Component Usage

import { Component } from '@angular/core';
import { BrMaskDirective } from 'br-angular-masker';

@Component({
  standalone: true,
  selector: 'app-example',
  imports: [BrMaskDirective],
  template: `
    <input [brMasker]="{ person: true }" />
  `
})
export class ExampleComponent {}

Ionic Usage (ion-input)

<ion-item>
  <ion-input
    placeholder="CPF / CNPJ"
    [brMasker]="{ person: true }">
  </ion-input>
</ion-item>

Configuration API

BrMaskConfig

export interface BrMaskConfig {
  mask?: string;
  type?: 'num' | 'text';

  userCaracters?: boolean;

  person?: boolean;
  cpf?: boolean;
  cnpj?: boolean;

  phone?: boolean;
  phoneNotDDD?: boolean;

  money?: boolean;
  percent?: boolean;

  decimal?: number;
  decimalCaracter?: string;
  thousand?: string;

  numberAndTousand?: boolean;
}

Mask Options and Examples

Custom Mask

<input [brMasker]="{ mask: '00:00', type: 'num' }" />

Result:

12:34

CPF / CNPJ (Automatic)

<input [brMasker]="{ person: true }" />

Formats:

• 999.999.999-99
• 99.999.999/9999-99

Phone with DDD

<input [brMasker]="{ phone: true }" />

Formats:

• (99) 9999-9999
• (99) 99999-9999

Phone without DDD

<input [brMasker]="{ phoneNotDDD: true }" />

Formats:

• 9999-9999
• 99999-9999

Money (Brazilian Real)

<input [brMasker]="{ money: true }" />

Result:

999,99

Money with Custom Decimal and Thousand

<input
  [brMasker]="{
    money: true,
    thousand: ',',
    decimalCaracter: '.',
    decimal: 3
  }"
/>

Result:

1,234.567

Percent

<input [brMasker]="{ percent: true }" />

Result:

50%

Number with Thousand Separator

<input [brMasker]="{ numberAndTousand: true, thousand: ',' }" />

Result:

1,234,567

Programmatic Usage (Service)

Import the Service

import { BrMaskService } from 'br-masker';

Example

constructor(private brMask: BrMaskService) {}

formatPhone(): string {
  return this.brMask.writeCreateValue(
    '99999999999',
    { phone: true }
  );
}

Migration from br-mask

| br-mask | br-masker | |--------|-----------| | [brmasker] | [brMasker] | | BrMaskModel | BrMaskConfig | | writeCreateValue() | Same | | Angular 11 | Angular 20+ |

Notes

• Masking is visual only
• FormControl values are not mutated
• Cursor position preservation is not enabled
• CPF/CNPJ validation is not included

Roadmap

• ControlValueAccessor support
• Cursor-safe masking
• CPF / CNPJ validation
• Unit tests

License

MIT