MaskedInput
Moldes
Dinheiro
Vai para o servidor como 248000 centavos.
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
| Prop | Tipo | Padrão |
|---|---|---|
maskobrigatória0.4.0Nome de molde pronto, molde escrito na mao, ou `moeda`. | Mask | sem padrão |
defaultValue0.4.0O texto inicial, quando o componente controla o proprio estado. | string | "" |
onValueChange0.4.0Chamado 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 |
placeholderO exemplo do formato. | string | sem padrão |
render0.4.0Troca 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.0 | ControlSize | null | sem padrão |
value0.4.0O valor, quando quem usa controla o estado: o cru ou o texto ja com mascara, que a tela sempre mostra pontuado. | string | sem padrão |
Além destas, a peça aceita className, style, id e children, repassados ao elemento de baixo.