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

$3

``bash
npm install --save ngx-brazil@21.0.0
`

$3

`bash

Angular 20.x.x

npm install --save ngx-brazil@20.1.1

Angular 19.x.x

npm install --save ngx-brazil@19.0.0

Angular 18.x.x

npm install --save ngx-brazil@18.0.4

Angular 17.x.x

npm install --save ngx-brazil@17.0.0

Angular 16.x.x

npm install --save ngx-brazil@16.0.0

Angular 15.x.x

npm install --save ngx-brazil@15.0.0
`

---

✨ Funcionalidades

$3

- ✅ 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

$3

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

$3

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

$3

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

$3

- ✅ 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

$3

`typescript
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:

type="text"
formControlName="cpf"
cpf
[textMask]="{mask: MASKS.cpf.textMask}"
placeholder="CPF">

type="text"
formControlName="cnpj"
cnpj
[textMask]="{mask: MASKS.cnpj.textMask}"
placeholder="CNPJ">


})
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]]
});
}
}
`

$3

`typescript
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

$3

`typescript
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)]
]
});
}
}
`

$3

`html

type="text"
formControlName="cpf"
cpf
[textMask]="{mask: MASKS.cpf.textMask}">


type="text"
formControlName="cnpj"
cnpj
[textMask]="{mask: MASKS.cnpj.textMask}">


type="text"
formControlName="phoneNumber"
phoneNumber
[textMask]="{mask: MASKS.phoneNumber.textMaskFunction}">


type="text"
formControlName="cep"
cep
[textMask]="{mask: MASKS.cep.textMask}">


type="text"
formControlName="inscricaoestadual"
inscricaoestadual="sp"
[textMask]="{mask: MASKS.inscricaoestadual[estado].textMask}">
`

$3

`html

CPF: {{ '12345678910' | cpf }}

CNPJ: {{ '40841253000102' | cnpj }}

RG: {{ 'MG10111222' | rg }}

IE: {{ '0018192630048' | inscricaoestadual: 'mg' }}

Telefone: {{ '1139998888' | phoneNumber }}

Valor: {{ '123.23' | currencyBrazil }}

Número: {{ '123.23' | numberBrazil }}

Número: {{ '123.23' | numberBrazil: 0 }}

`

---

🛠️ 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

$3

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

`typescript
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

$3

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

`typescript
import { NgxBrazilMASKS } from 'ngx-brazil';

// Uso em componente
public MASKS = NgxBrazilMASKS;
`

$3

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

!Demo Image

---

🤝 Contribuindo

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

$3

1. Faça um fork do projeto
2. Instale as dependências globais:
`bash
npm i -g rimraf ng-packagr @angular/compiler-cli @angular/compiler tslib
`
3. Clone e instale as dependências:
`bash
git clone https://github.com/seu-usuario/ngx-brazil.git
cd ngx-brazil/ngx-brazil
npm install
`
4. Compile a biblioteca:
`bash
npm run build:lib
`
5. Execute o projeto de demonstração:
`bash
npm run start
`

$3

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:
`bash
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: thiago.valente@fitideias.com.br
- 🐛 Reportar Bug
- 💡 Sugerir Feature

---

Desenvolvido com ❤️ para a comunidade Angular brasileira