Pular para o conteúdo
Formulário

MaskedInput

/componentes/masked-input.mdmarkdown cru, para quem lê com agent em vez de olho

Moldes

Dinheiro

Vai para o servidor como 248000 centavos.

Importar
import { MaskedInput } from '@rivocode/ui'

Quando usar

Campo com máscara guiada por molde: 9 é dígito, A é letra, * é os dois, e o resto é literal que a máscara põe sozinha.

Moldes prontos: cpf, cnpj, cpfCnpj, cep, telefone, data, hora, placa, cartao, boleto e moeda. Aceita molde escrito à mão, como 99-99/9999.

onValueChange entrega o cru e, no segundo argumento, o texto pontuado, a mesma ordem do nativo. Guarde o cru: a pontuação muda com o tempo e o dado deixa de bater. O dinheiro sai também em centavos, por toCents(), para o servidor receber inteiro em vez de ponto flutuante.

O telefone troca de molde entre o fixo e o celular sozinho, e o boleto também: a linha começa no molde de banco, de 47 dígitos, e passa para o de convênio, de 48 em quatro blocos (84630000000-3 29990296202-4 …), quando o primeiro dígito é 8, que é como toda conta de consumo e todo tributo começam. Os 44 dígitos do código de barras, colados de um leitor óptico ou de um PDF, ficam sem pontuação: eles não são a linha, e a pontuação de 47 casas neles mentiria.

A placa e o cartão também trocam sozinhos. A placa decide pela quinta casa: dígito é a placa antiga, que sai com hífen (ABC-1234), e letra é a Mercosul (ABC1D23), a mesma regra do isValidPlate. O cartão decide pelo começo do número: 34 e 37 são Amex, de 15 dígitos em 4-6-5; 300 a 305, 36, 38 e 39 são Diners, de 14 em 4-6-4; o resto fica nos 16 dígitos em quatro blocos.

O CNPJ aceita letra: desde julho de 2026 a Receita emite CNPJ alfanumérico, com letra ou dígito nas doze primeiras casas e dígito nos dois verificadores. A letra sobe a caixa sozinha, e o CNPJ só de números continua saindo igual. Por isso o cnpj abre o teclado de texto no celular, e não o numérico.

O cpfCnpj é o campo "CPF ou CNPJ" do checkout, do cadastro de cliente e da nota fiscal, num campo só. Ele começa no molde do CPF e passa ao do CNPJ quando a pessoa digita a décima segunda casa, ou uma letra, que só cabe no CNPJ alfanumérico; apagar até onze casas volta ao CPF. Como o CNPJ aceita letra, ele abre o teclado de texto, e não o numérico. O placeholder é o do CPF, que é o molde do campo vazio: os dois formatos juntos passam de trinta e cinco caracteres e saem cortados no celular. Quem diz que o CNPJ também serve é o rótulo, "CPF ou CNPJ". Quem confere é o isValidCpfOrCnpj.

O molde também diz ao navegador o que o campo pede, para o celular oferecer o preenchimento (WCAG 1.3.5): telefone sai com autoComplete="tel-national" e inputMode="tel", cep com postal-code e cartao com cc-number. CPF e CNPJ não têm nome no padrão do autocomplete, e ficam sem. O autoComplete e o inputMode que você passar vencem a sugestão.

O molde pronto traz também o placeholder do formato: 000.000.000-00 no cpf, (00) 00000-0000 no telefone, ABC1D23 na placa, dd/mm/aaaa na data, 000.000.000-00 no cpfCnpj, 0,00 na moeda. Molde escrito à mão nasce sem, porque só você sabe o exemplo que ele pede. O placeholder passado vence, e placeholder="" desliga.

Os onze moldes

Nome Molde Sai como Placeholder
cpf 999.999.999-99 123.456.789-01 000.000.000-00
cnpj **.***.***/****-99 12.345.678/0001-90, 12.ABC.345/01DE-35 00.000.000/0000-00
cpfCnpj 999.999.999-99 até onze casas, **.***.***/****-99 daí em diante 529.982.247-25, 11.222.333/0001-81 000.000.000-00
cep 99999-999 58000-000 00000-000
telefone (99) 99999-9999 (83) 99999-1234 (00) 00000-0000
data 99/99/9999 05/08/2026 dd/mm/aaaa
hora 99:99 14:30 hh:mm
placa AAA9A99 ou AAA-9999 ABC1D23, ABC-1234 ABC1D23
cartao 9999 9999 9999 9999, 9999 999999 99999 ou 9999 999999 9999 4111 1111 1111 1111, 3782 822463 10005 0000 0000 0000 0000
boleto 99999.99999 99999.999999 99999.999999 9 99999999999999 00190.00009 01149.718601 68524.522114 6 75860000102656 00000.00000 00000.000000 00000.000000 0 00000000000000
moeda - 2.480,00 0,00

moeda é o único sem molde: em dinheiro os centavos vêm primeiro e a casa anda para a esquerda a cada dígito, o contrário de todo o resto. Os outros dez vivem em MASKS (o cpfCnpj guarda lá o molde do CNPJ, o mais longo), e MaskName é o nome de um deles. O tipo Mask da prop aceita esse nome, moeda, ou um molde escrito à mão.

O cru de moeda são os dígitos do que está na tela, com o zero da frente: 0,05 entrega 005, e 12,00 entrega 1200. Os dois últimos são sempre os centavos, e o nativo entrega o mesmo texto.

Nome de molde digitado errado não vira molde literal: mask="dinheiro" avisa no console em desenvolvimento e deixa o texto passar cru, em vez de escrever "dinheiro" dentro do campo.

Conferir o documento

A máscara põe a pontuação, e não diz se o número existe. Quem confere é isValidCpf e isValidCnpj, pelos dígitos verificadores, e o isValidCpfOrCnpj, que decide pelo tamanho (onze casas é CPF, catorze é CNPJ) e confere o verificador do que achou. Os dois aceitam o texto com ou sem pontuação, e o isValidCnpj já faz a conta do CNPJ alfanumérico: cada letra vale o código dela menos 48.

CNH, título de eleitor, PIS, RENAVAM e placa têm a sua: isValidCnh, isValidVoterId, isValidPis, isValidRenavam e isValidPlate. A linha digitável do boleto se confere com isValidBoletoLine, e parseBoleto lê dela o banco, o valor em centavos e o vencimento. O guia Documentos brasileiros diz o que cada conta confere.

const schema = z.object({
  cnpj: z.string().refine(isValidCnpj, 'Use o formato 00.000.000/0000-00'),
  document: z.string().refine(isValidCpfOrCnpj, 'Use um CPF ou CNPJ com os dígitos certos'),
})

Valide ao sair do campo, e não a cada tecla: o documento pela metade é sempre inválido, e acusar quem ainda está digitando é ruído.

No formulário

Com o @rivocode/ui/form, o campo entra pelo forValue, que liga o onValueChange ao react-hook-form: o formulário guarda o cru, o primeiro argumento, e o campo continua mostrando o texto pontuado. O forValue leva também o onBlur, e o useZodForm nasce com mode: 'onTouched': o validador confere ao sair do campo, e depois do primeiro erro a cada tecla.

<FormField name="document" label="CNPJ do fornecedor">
  {(field) => <MaskedInput {...forValue(field)} mask="cnpj" />}
</FormField>

O valor que chega por value sempre aparece com a máscara, mesmo cru: um "11222333000181" vindo do servidor aparece 11.222.333/0001-81.

As máscaras fora do campo

A mesma lógica sai como função, para o texto que a tela mostra e nunca recebe digitação: a coluna de CPF de uma tabela, o CNPJ no cabeçalho de um recibo, o telefone que voltou cru do servidor.

Função Para que
applyMask(texto, mask) Aplica pelo nome do molde, molde cru ou moeda
applyPattern(texto, molde) Aplica um molde direto, sem passar pelos nomes
applyCurrencyMask(texto) Só o dinheiro, da direita para a esquerda
unmask(texto) Tira a pontuação e devolve o que a pessoa digitou
toCents(texto) 1.234,56 vira 123456, sem ponto flutuante no meio
phonePatternFor(texto) Diz qual dos dois moldes de telefone o texto pede
<TableCell>{applyMask(cliente.document, 'cnpj')}</TableCell>

phonePatternFor devolve um molde, e não um texto: o telefone brasileiro tem oito ou nove casas depois do DDD e o molde muda no meio da digitação, então quem formata telefone à mão pergunta a ele primeiro e passa a resposta para o applyPattern.

Quando não usar

Para dinheiro, prefira CurrencyInput ao molde moeda: ele entra e sai em centavos inteiros, digita da direita como na maquininha e lê o valor colado. Quantidade com passo (parcelas, dias de prazo) é NumberField.

Data e hora têm peça própria: o DatePicker traz o calendário e confere se a data existe, e o TimeField confere a hora; os moldes data e hora só põem a pontuação. O CEP que preenche o endereço é PostalCodeField, e o código que chega por SMS é OTPField.

E-mail e chave Pix vão em Input, sem máscara: a chave pode ser CPF, CNPJ, e-mail, celular ou aleatória, e nenhum molde cobre as cinco.

No React Native

Traduz, com os mesmos moldes: os nomes prontos (cpf, cnpj, cpfCnpj, cep, data, hora, placa, cartao, telefone, boleto e moeda) e o molde escrito à mão, com 9 para dígito, A para letra e * para os dois, saem de um arquivo só, compartilhado pelos dois pacotes.

O que muda é o value: aqui ele é o valor limpo, sem pontuação e com letra em caixa alta, porque a máscara é do campo e o dado não a carrega; o web aceita também o texto pontuado. O onValueChange tem a ordem do web: o limpo primeiro e o texto com máscara no segundo argumento. Com moeda, o limpo é o mesmo cru do web, os dígitos do que está na tela: 0,05 entrega 005, e 12,00 entrega 1200.

O molde de telefone, CEP e cartão põe sozinho o autoComplete (tel-national, postal-code, cc-number), o textContentType do iOS e, no telefone, o teclado phone-pad; a prop que você passar vence a sugestão.

API

PropTipoPadrão
maskobrigatória0.4.0

Nome de molde pronto, molde escrito na mao, ou `moeda`.

Masksem padrão
defaultValue0.4.0

O texto inicial, quando o componente controla o proprio estado.

string""
onValueChange0.4.0

Chamado a cada tecla, com o cru primeiro e o texto da tela depois, na mesma ordem do nativo.

((raw: string, masked: string) => void)sem padrão
placeholder

O exemplo do formato.

stringsem padrão
render0.4.0

Troca o elemento HTML da peça por outra tag, ou a compõe com outro componente.

ComponentRenderFn<HTMLProps, FieldControlState> | ReactElement<unknown, string | JSXElementConstructor<any>>sem padrão
size0.4.0ControlSize | nullsem padrão
value0.4.0

O valor, quando quem usa controla o estado: o cru ou o texto ja com mascara, que a tela sempre mostra pontuado.

stringsem padrão

Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.

@rivocode/ui, 149 peças no catálogo. Esta página é gerada dos mesmos arquivos que alimentam o design system, então ela não envelhece sozinha.

Feito por RivoCode.