Pular para o conteúdo
Formulário

PostalCodeField

/componentes/postal-code-field.mdmarkdown cru, para quem lê com agent em vez de olho

Com ViaCEP

O endereço se preenche sozinho.

Os quatro finais

Apague um número e digite de novo: 58038-000.

Qualquer CEP que não comece por zero: 99999-999.

Um CEP que comece por zero: 01310-100.

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

Quando usar

O campo de CEP que busca o endereço: põe a máscara 99999-999 e, quando a pessoa completa os 8 dígitos, chama a sua função lookup e entrega o endereço por onAddress, para o resto do formulário se preencher sozinho.

<Field>
  <FieldLabel>CEP</FieldLabel>
  <PostalCodeField lookup={lookupViaCep} onAddress={fillAddress} />
</Field>

A biblioteca não chama serviço nenhum. Quem busca é a função que você passa: ela recebe os 8 dígitos e o signal da busca, e devolve { street, district, city, state }, ou null quando o CEP não existe. Você escolhe o serviço (ViaCEP, BrasilAPI, o seu próprio servidor), a política de cache e o que fazer com o dado.

Com ViaCEP

async function lookupViaCep(cep: string, signal: AbortSignal): Promise<PostalAddress | null> {
  const response = await fetch(`https://viacep.com.br/ws/${cep}/json/`, { signal })
  if (!response.ok) throw new Error(`ViaCEP respondeu ${response.status}`)
  const data = await response.json()
  if (data.erro) return null
  return { street: data.logradouro, district: data.bairro, city: data.localidade, state: data.uf }
}

Três regras de contrato, e a função acima segue as três:

  • null é "não existe". O ViaCEP responde 200 com { "erro": true } para CEP que não existe, e é a função que traduz isso para null.
  • Rejeitar é falha de rede. Timeout, sem conexão, servidor fora do ar: a peça mostra outro aviso, com o "Tentar de novo". Ele some quando a busca recomeça, e o foco volta para o campo antes disso.
  • Repasse o signal ao fetch. Quando a pessoa troca o CEP no meio da busca, a peça cancela a anterior. A resposta velha é descartada de qualquer jeito, mas com o signal a requisição para de verdade.

Os quatro finais

Estado Na tela No leitor de tela
Buscando giro no fim do campo, e o campo com aria-busy; com movimento reduzido, o giro para e o "Buscando endereço…" aparece escrito embaixo "Buscando endereço…"
Achou um visto no fim do campo, e onAddress chamado "Endereço encontrado."
Não achou aviso em vermelho embaixo, campo inválido o próprio aviso
Falha de rede aviso neutro com "Tentar de novo", campo não inválido o próprio aviso

A falha de rede não marca o campo como inválido de propósito: o CEP pode estar certo, e a pessoa ainda consegue preencher o endereço à mão. O aviso sai ligado ao campo por aria-describedby, junto com a FieldDescription que já estivesse lá, e todos os anúncios saem numa região viva que existe antes da primeira busca.

A busca só roda quando a pessoa digita. defaultValue, ou um value que chega do servidor ao editar um cadastro, não dispara nada: buscar ali sobrescreveria o endereço que a pessoa já tinha acertado à mão. Apagar um dígito cancela a busca em curso e limpa o aviso. onStatusChange conta cada troca de estado, para quem quer travar o botão de enviar enquanto busca.

No formulário

Com o FormField, guarde os dígitos pelo onValueChange e preencha o resto pelo setValue do formulário:

const form = useZodForm(schema, { defaultValues: { cep: '', street: '', city: '' } })

<FormField name="cep" label="CEP">
  {(field) => (
    <PostalCodeField
      name={field.name}
      value={field.value}
      onBlur={field.onBlur}
      onValueChange={(digits) => field.onChange(digits)}
      lookup={lookupViaCep}
      onAddress={(address) => {
        form.setValue('street', address.street)
        form.setValue('city', address.city)
      }}
    />
  )}
</FormField>

O erro do schema (z.string().length(8), por exemplo) continua saindo pelo FormField, embaixo do campo, e convive com o aviso da busca.

Partes

classNames alcança cada nó pelo nome: input, suffix (o giro e o visto), message e retry. className veste a raiz, que embrulha o campo e o aviso.

Quando não usar

  • CEP sem busca de endereço é MaskedInput com mask="cep". Se a tela não vai preencher nada com a resposta, a busca só gasta rede e mostra um giro que não serve a ninguém.
  • Endereço fora do Brasil não tem CEP. Use Input com o rótulo do país ("ZIP code", "Código postal"), sem máscara.
  • Escolher entre endereços já cadastrados é Combobox, com a lista de endereços do cliente. O PostalCodeField é para escrever um endereço novo.

No React Native

Traduz, com a mesma lookup, o mesmo onAddress e os mesmos quatro finais, e com a busca cancelada quando o CEP muda: a regra mora num arquivo só, compartilhado pelos dois pacotes. O campo é controlado, como todo o nativo: value e onValueChange recebem os dígitos, sem a pontuação, e o onValueChange traz o CEP pontuado no segundo argumento, na mesma ordem do web.

O giro fica no fim do campo, o aviso embaixo dele, e cada troca de estado sai pelo anúncio do leitor de tela do sistema. O "Tentar de novo" da falha de rede é um botão de verdade, com alvo de toque inteiro.

As partes vestem pelo mesmo classNames do web: input, suffix, message e retry. O suffix só existe enquanto a busca corre, porque aqui não há o visto do endereço achado.

API

PropTipoPadrão
lookupobrigatória

A busca do endereco, escrita por quem usa: recebe os 8 digitos e o `signal` da busca, e devolve o endereco ou `null` quando o CEP nao existe.

PostalCodeLookupsem padrão
classNames

Classe por parte: `input`, `suffix` (o giro e o visto), `message` e `retry`.

Partial<Record<"input" | "message" | "retry" | "suffix", string>>sem padrão
defaultValue

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

string""
labels

Os textos da peca, um a um: `searching`, `found`, `notFound`, `failed` e `retry`.

Partial<{ searching: string; found: string; notFound: string; failed: string; retry: string; }>sem padrão
onAddress

Chamado quando a busca acha o endereco, com ele e os 8 digitos.

((address: PostalAddress, postalCode: string) => void)sem padrão
onStatusChange

Chamado a cada troca de estado da busca: `searching`, `found`, `notFound`, `failed`, `idle`.

((status: PostalCodeStatus) => void)sem padrão
onValueChange

Chamado a cada tecla, com os digitos primeiro e o texto mascarado depois, na mesma ordem do nativo.

((digits: string, masked: string) => void)sem padrão
render

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
sizeControlSize | nullsem padrão
value

O valor, quando quem usa controla o estado: os digitos ou o texto com mascara.

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.