Ajax UI
Components/CEP Input

CEP Input

Brazilian postal-code field with the 00000-000 mask and a single-fire completion hook - wire it to ViaCEP or BrasilAPI for address autofill without debouncing.

Type any 8 digits - the lookup fires once when the CEP completes.

Installation

npx @ajax-ui/cli add cep-input

Props

  • value / defaultValue - raw digits, no mask. Set value + onValueChange for controlled.
  • onValueChange(digits, complete) - fires on every keystroke.
  • onComplete(cep) - fires exactly once each time the field reaches 8 digits; editing below 8 re-arms it. Wire your address lookup here.
  • loading - shows an inline spinner; drive it from your lookup request.

Wiring ViaCEP

<CepInput
  loading={loading}
  onComplete={async (cep) => {
    setLoading(true);
    const res = await fetch(`https://viacep.com.br/ws/${cep}/json/`);
    const data = await res.json();
    if (!data.erro) fillAddress(data); // logradouro, bairro, localidade, uf
    setLoading(false);
  }}
/>

Accessibility

  • Native input with autocomplete="postal-code" - browser autofill works.
  • inputMode="numeric" opens the digit pad on mobile.
  • The spinner carries role="status" with an accessible label.