Ngx-Brazil 🇧🇷

Biblioteca Angular com pipes, diretivas, validadores e máscaras para aplicações brasileiras

Ngx-Brazil é uma biblioteca completa para trabalhar com dados brasileiros em aplicações Angular. Fornece validação, formatação e máscaras para documentos, telefones, endereços e outros dados específicos do Brasil.

Nota: Este projeto é um fork de ng-brazil mantido e atualizado para versões mais recentes do Angular.

📦 Instalação

Angular 21.x.x

npm install --save [email protected]

Versões anteriores

# Angular 20.x.x
npm install --save [email protected]

# Angular 19.x.x
npm install --save [email protected]

# Angular 18.x.x
npm install --save [email protected]

# Angular 17.x.x
npm install --save [email protected]

# Angular 16.x.x
npm install --save [email protected]

# Angular 15.x.x
npm install --save [email protected]

✨ Funcionalidades

Documentos

• ✅ CPF - Validação, formatação e máscara
• ✅ CNPJ - Validação, formatação e máscara
• ✅ RG - Validação, formatação e máscara
• ✅ Título de Eleitor - Validação e formatação
• ✅ PIS/PASEP - Validação e formatação

Endereço e Localização

• ✅ CEP - Validação, formatação e máscara
• ✅ Inscrição Estadual - Validação por estado e formatação

Veículos

• ✅ Placa de Veículo - Validação e formatação
• ✅ RENAVAM - Validação e formatação

Contato

• ✅ Telefone Fixo - Validação, formatação e máscara
• ✅ Celular - Validação, formatação e máscara

Formatação

• ✅ Moeda (R$) - Formatação brasileira
• ✅ Número - Formatação com separadores brasileiros
• ✅ Percentual - Formatação de percentuais
• ✅ Hora - Formatação de horários

🚀 Uso Rápido

Com Standalone Components (Angular 14+)

import { Component } from '@angular/core';
import { FormBuilder, FormGroup, ReactiveFormsModule, Validators } from '@angular/forms';
import { NgxBrazil, NgxBrazilMASKS, NgxBrazilValidators } from 'ngx-brazil';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [
    ReactiveFormsModule,
    NgxBrazil
  ],
  template: `
    <form [formGroup]="form">
      <input 
        type="text" 
        formControlName="cpf" 
        cpf 
        [textMask]="{mask: MASKS.cpf.textMask}"
        placeholder="CPF">
      
      <input 
        type="text" 
        formControlName="cnpj" 
        cnpj 
        [textMask]="{mask: MASKS.cnpj.textMask}"
        placeholder="CNPJ">
    </form>
  `
})
export class AppComponent {
  public MASKS = NgxBrazilMASKS;
  public form: FormGroup;

  constructor(private fb: FormBuilder) {
    this.form = this.fb.group({
      cpf: ['', [Validators.required, NgxBrazilValidators.cpf]],
      cnpj: ['', [Validators.required, NgxBrazilValidators.cnpj]]
    });
  }
}

Com NgModule (Compatibilidade)

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { ReactiveFormsModule } from '@angular/forms';
import { NgxBrazil } from 'ngx-brazil';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    ReactiveFormsModule,
    NgxBrazil
  ],
  bootstrap: [AppComponent]
})
export class AppModule { }

📖 Exemplos de Uso

Validadores em Formulários Reativos

import { FormBuilder, FormGroup, Validators } from '@angular/forms';
import { NgxBrazilValidators } from 'ngx-brazil';

export class MyComponent {
  form: FormGroup;
  estado = 'SP';

  constructor(private fb: FormBuilder) {
    this.form = this.fb.group({
      cpf: ['', [Validators.required, NgxBrazilValidators.cpf]],
      cnpj: ['', [Validators.required, NgxBrazilValidators.cnpj]],
      rg: ['', [Validators.required, NgxBrazilValidators.rg]],
      cep: ['', [Validators.required, NgxBrazilValidators.cep]],
      phoneNumber: ['', [Validators.required, NgxBrazilValidators.phoneNumber]],
      inscricaoestadual: [
        '', 
        [Validators.required, NgxBrazilValidators.inscricaoestadual(this.estado)]
      ]
    });
  }
}

Máscaras em Inputs

<!-- CPF -->
<input 
  type="text" 
  formControlName="cpf" 
  cpf 
  [textMask]="{mask: MASKS.cpf.textMask}">

<!-- CNPJ -->
<input 
  type="text" 
  formControlName="cnpj" 
  cnpj 
  [textMask]="{mask: MASKS.cnpj.textMask}">

<!-- Telefone -->
<input 
  type="text" 
  formControlName="phoneNumber" 
  phoneNumber 
  [textMask]="{mask: MASKS.phoneNumber.textMaskFunction}">

<!-- CEP -->
<input 
  type="text" 
  formControlName="cep" 
  cep 
  [textMask]="{mask: MASKS.cep.textMask}">

<!-- Inscrição Estadual -->
<input 
  type="text" 
  formControlName="inscricaoestadual" 
  inscricaoestadual="sp" 
  [textMask]="{mask: MASKS.inscricaoestadual[estado].textMask}">

Pipes para Formatação

<!-- CPF -->
<p>CPF: {{ '12345678910' | cpf }}</p>
<!-- Resultado: 123.456.789-10 -->

<!-- CNPJ -->
<p>CNPJ: {{ '40841253000102' | cnpj }}</p>
<!-- Resultado: 40.841.253/0001-02 -->

<!-- RG -->
<p>RG: {{ 'MG10111222' | rg }}</p>
<!-- Resultado: MG-10.111.222 -->

<!-- Inscrição Estadual -->
<p>IE: {{ '0018192630048' | inscricaoestadual: 'mg' }}</p>
<!-- Resultado: 001.819.263/0048 -->

<!-- Telefone -->
<p>Telefone: {{ '1139998888' | phoneNumber }}</p>
<!-- Resultado: (11) 3999-8888 -->

<!-- Moeda -->
<p>Valor: {{ '123.23' | currencyBrazil }}</p>
<!-- Resultado: R$ 123,23 -->

<!-- Número -->
<p>Número: {{ '123.23' | numberBrazil }}</p>
<!-- Resultado: 123,23 -->

<!-- Número sem decimais -->
<p>Número: {{ '123.23' | numberBrazil: 0 }}</p>
<!-- Resultado: 123 -->

🛠️ Tecnologias Compatíveis

Este projeto foi testado e é compatível com:

• ✅ Angular 15, 16, 17, 18, 19, 20 e 21
• ✅ Angular Material
• ✅ Ionic (pipes, diretivas e validadores funcionam; máscaras podem ter limitações)

📚 API Reference

Validadores

Todos os validadores estão disponíveis em NgxBrazilValidators:

import { NgxBrazilValidators } from 'ngx-brazil';

// Uso em FormControl
const cpfControl = new FormControl('', [
  Validators.required,
  NgxBrazilValidators.cpf
]);

Validadores disponíveis:

• cpf - Valida CPF
• cnpj - Valida CNPJ
• rg - Valida RG
• cep - Valida CEP
• phoneNumber - Valida telefone fixo
• cellphone - Valida celular
• inscricaoestadual(estado) - Valida Inscrição Estadual (requer estado)
• renavam - Valida RENAVAM
• pispasep - Valida PIS/PASEP
• licensePlate - Valida placa de veículo
• titulo - Valida Título de Eleitor
• currency - Valida moeda
• number - Valida número
• time - Valida horário
• percentage - Valida percentual

Máscaras

Todas as máscaras estão disponíveis em NgxBrazilMASKS:

import { NgxBrazilMASKS } from 'ngx-brazil';

// Uso em componente
public MASKS = NgxBrazilMASKS;

Pipes

Todos os pipes podem ser usados diretamente nos templates:

• cpf - Formata CPF
• cnpj - Formata CNPJ
• rg - Formata RG
• cep - Formata CEP
• phoneNumber - Formata telefone
• cellphone - Formata celular
• inscricaoestadual - Formata Inscrição Estadual (requer estado como parâmetro)
• currencyBrazil - Formata moeda brasileira
• numberBrazil - Formata número brasileiro
• time - Formata horário
• percentage - Formata percentual

🎯 Demo

Veja a biblioteca em ação:

• 🌐 Demo Online no StackBlitz
• 📦 Repositório no GitHub

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, leia nosso Guia de Contribuição e Código de Conduta antes de começar.

Setup de Desenvolvimento

1. Faça um fork do projeto
2. Instale as dependências globais:

   npm i -g rimraf ng-packagr @angular/compiler-cli @angular/compiler tslib

3. Clone e instale as dependências:

   git clone https://github.com/seu-usuario/ngx-brazil.git
   cd ngx-brazil/ngx-brazil
   npm install

4. Compile a biblioteca:

   npm run build:lib

5. Execute o projeto de demonstração:

   npm run start

Publicando uma Nova Versão

1. Atualize a versão em:
   • ngx-brazil/package.json
   • ngx-brazil/ngx-brazil/package.json
   • README.md (seções de instalação)
2. Compile e publique:

   npm run build:lib
   cd dist/ngx-brazil
   npm login
   npm publish

📝 Licença

Este projeto está licenciado sob a MIT License.

🙏 Agradecimentos

Este projeto é um fork de ng-brazil criado por Mario Mol. Agradecemos ao autor original por criar essa excelente base.

📞 Suporte

• 📧 Email: [email protected]
• 🐛 Reportar Bug
• 💡 Sugerir Feature

Desenvolvido com ❤️ para a comunidade Angular brasileira