all_br_forms

🇧🇷 Português | 🇺🇸 English

Máscaras de entrada brasileiras para Flutter, prontas para TextField e TextFormField. Formate documentos, contatos, datas, valores, veículos e medidas enquanto o usuário digita, com comportamento previsível e testado.

Por que usar?

• 24 máscaras com construtores const e uma única importação.
• Digitação, deleção, colagem, truncamento e idempotência cobertos por testes.
• Formatos dinâmicos para CPF/CNPJ, telefone, validade e placa.
• CNPJ numérico e alfanumérico no padrão brasileiro de 2026.
• Integração direta com all_br_validations, sem duplicar regras semânticas.
• Nenhuma gerência de estado exigida; all_observer é apenas uma integração opcional demonstrada no app de exemplo.

Onde usar

• Cadastros de pessoas e empresas.
• Checkout, cobrança e dados de cartão.
• Endereços, contatos e documentos brasileiros.
• Veículos, produtos fiscais e processos administrativos.
• Campos de data, hora, moeda e medidas.

Catálogo das 24 máscaras

Categoria	Máscaras
Documentos	CpfMask, CnpjMask, CnpjAlfaMask, CpfOuCnpjMask, CnsMask, CertNascimentoMask
Contato e endereço	PhoneMask, CepMask
Pagamentos e valores	CardMask, CardExpiryMask, CurrencyMask, CentavosMask, IofMask
Datas e tempo	DateMask, TimeMask, ExpiryMask
Veículos, produtos e processos	PlacaMask, NcmMask, CestMask, NupMask
Medidas	AlturaMask, PesoMask, TemperaturaMask, KmMask

A referência completa informa limite, formato final e comportamento de cada classe.

Instalação

dependencies:
  all_br_forms: ^1.0.0

import 'package:all_br_forms/all_br_forms.dart';

Se a aplicação também fizer validação semântica diretamente, declare e importe o core explicitamente:

dependencies:
  all_br_forms: ^1.0.0
  all_br_validations: ^1.0.0

import 'package:all_br_forms/all_br_forms.dart';
import 'package:all_br_validations/all_br_validations.dart';

Flutter puro

As máscaras são TextInputFormatter; não exigem controller ou pacote de estado:

TextField(
  keyboardType: TextInputType.number,
  inputFormatters: const [CpfMask()],
  decoration: const InputDecoration(labelText: 'CPF'),
)

Máscara com validação automática por BrZod

A máscara cuida da edição; o BrZod valida o valor. Com AutovalidateMode.onUserInteraction, o campo apresenta o erro depois que o usuário começa a interagir:

TextFormField(
  keyboardType: TextInputType.phone,
  inputFormatters: const [PhoneMask()],
  decoration: const InputDecoration(labelText: 'Celular'),
  autovalidateMode: AutovalidateMode.onUserInteraction,
  validator: BrZod().required().phone().build,
)

O mesmo padrão atende às principais máscaras:

Máscara	Validador
CpfMask	BrZod().required().cpf().build
CnpjMask	BrZod().required().cnpj().build
CnpjAlfaMask	BrZod().required().cnpjAlfa().build
CpfOuCnpjMask	BrZod().required().cpfOuCnpj().build
CepMask	BrZod().required().cep().build
PhoneMask	BrZod().required().phone().build
CnsMask	remova os espaços com BrInputMask.digits antes de .cns()
PlacaMask	remova o hífen antes de .placa()

Para máscaras sem método equivalente no BrZod, use uma regra direta de AllValidations no validator.

validator: (value) => BrZod()
    .required()
    .placa()
    .build((value ?? '').replaceAll('-', '')),

Outros usos comuns:

const cpfOuCnpj = TextField(
  inputFormatters: [CpfOuCnpjMask()], // muda de formato automaticamente
);

const valor = TextField(
  keyboardType: TextInputType.number,
  inputFormatters: [CurrencyMask()], // 123456 → R$ 1.234,56
);

const empresa = TextField(
  textCapitalization: TextCapitalization.characters,
  inputFormatters: [CnpjAlfaMask()], // 12ABC34501DE35 → máscara oficial
);

Integração opcional

As máscaras não exigem gerenciador de estado. O app de exemplo também mostra uma integração opcional com all_observer para feedback reativo enquanto o usuário digita.

Máscara não é validação

Uma máscara controla apresentação e caracteres aceitos. Ela não comprova dígitos verificadores, datas reais, titularidade ou existência oficial.

Necessidade	Use
Formatar enquanto digita	all_br_forms
Validar documentos e formatos	all_br_validations
Fazer as duas coisas	máscara no inputFormatters e regra no validator

Contrato de edição

Os formatadores removem caracteres incompatíveis, respeitam o limite de cada campo e reformatam o valor completo recebido. A suíte cobre entrada incremental, deleção, colagem crua ou formatada, seleção, vazio e reaplicação da máscara.

Na versão 1.0.0, o cursor é colapsado no final do texto após a formatação. Aplicações que precisam preservar seleção ou edição no meio do valor devem considerar esse comportamento de experiência do usuário.

Exemplo executável

O app demonstra um formulário Flutter puro e, separadamente, uma integração opcional com all_observer:

cd example
flutter pub get
flutter run

Compatibilidade e documentação

• Dart >=3.0.0 <4.0.0.
• Flutter >=3.0.0.
• Referência das máscaras.
• Matriz completa de testes.
• Política de segurança.
• Como contribuir.

O pacote não armazena nem transmite o texto digitado. Proteja CPF, CNPJ, cartão, telefone e demais dados pessoais na aplicação e use somente dados sintéticos em testes e issues.

Licença MIT.