all_br_forms 1.0.1

Flutter input masks and form formatters for Brazilian documents, contact details, dates, currency, vehicles, and measurements.

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?

• 26 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 26 máscaras

Categoria	Máscaras
Documentos	CpfMask, CnpjMask, CnpjAlfaMask, CpfOuCnpjMask, CpfOuCnpjAlfaMask, CnsMask, CertNascimentoMask
Contato e endereço	PhoneMask, CepMask
Pagamentos e valores	PixKeyMask, 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.1

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.1
  all_br_validations: ^1.0.2

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'),
)

Chave PIX automática

PixKeyMask alterna automaticamente entre CPF, CNPJ numérico ou alfanumérico, celular, e-mail e chave aleatória EVP/GUID:

Entrada	Apresentação
52998224725	529.982.247-25
11222333000181	11.222.333/0001-81
00000000E08G12	00.000.000/E08G-12
21999998877	(21) 99999-8877
[e-mail]	[e-mail]
123e4567e12b02d10456426655440000	123e4567-e12b-02d1-0456-426655440000

TextFormField(
  keyboardType: TextInputType.text,
  inputFormatters: const [PixKeyMask()],
  decoration: const InputDecoration(labelText: 'Chave PIX'),
  validator: (value) => AllValidations.validatePixKey(
    PixKeyMask.normalize(value ?? ''),
  ).fold(
    (error) => error.message,
    (type) => null,
  ),
)

A normalização é necessária porque o DICT espera celular com +55 e CNPJ alfanumérico sem pontuação. O mesmo resultado informa qual tipo foi detectado:

final normalized = PixKeyMask.normalize(pixController.text);
final validation = AllValidations.validatePixKey(normalized);

validation.fold(
  (error) => print(error.message),
  (type) => print(type), // cpf, cnpj, phone, email ou random
);

O PixKeyType.cnpj representa tanto o CNPJ numérico quanto o alfanumérico. Quando essa distinção for necessária:

final isCnpjAlfanumerico =
    validation.successValue == PixKeyType.cnpj &&
    RegExp(r'[A-Z]').hasMatch(normalized);

CPF válido tem prioridade sobre celular quando ambos possuem 11 dígitos, seguindo a ordem de validatePixKey. No modo automático, o e-mail é detectado ao digitar @; quando o campo aceitar somente e-mail e precisar preservar pontuação antes do @, use const PixKeyMask.email().

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 documentoCompleto = TextField(
  keyboardType: TextInputType.text,
  textCapitalization: TextCapitalization.characters,
  inputFormatters: [CpfOuCnpjAlfaMask()], // CPF, CNPJ ou CNPJ alfanumérico
);

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.