reportValidity e setCustomValidity

A API de validação de restrições expõe dois métodos que controlam a interface de validação integrada do navegador: reportValidity (exibe a dica de ferramenta) e setCustomValidity (fornece uma mensagem de erro personalizada). Juntos, eles permitem personalizar as mensagens e manter a apresentação nativa.

checkValidity() retorna true/false silenciosamente, sem efeitos visuais. reportValidity() faz a mesma verificação, mas também focaliza o primeiro campo inválido e exibe a dica de validação do navegador. Escolha reportValidity quando quiser uma experiência nativa sem trabalho adicional.

Em assistentes com várias etapas, valide os campos de cada etapa antes de avançar: if (step.reportValidity()) { next(); }. O navegador cuida da exibição do erro e focaliza o campo que precisa de atenção, evitando que você tenha de reimplementar o gerenciamento do foco.

As mensagens padrão ("Preencha este campo") podem não corresponder ao seu tom. input.setCustomValidity("Username is required") substitui a mensagem padrão pelo seu texto. O campo de entrada será tratado como inválido até que você limpe a mensagem.

input.setCustomValidity("") remove a mensagem personalizada e reativa a validação normal. Chame-o sempre que fizer uma nova validação; caso contrário, mensagens personalizadas antigas continuarão presentes mesmo depois que o usuário corrigir o problema.

Para verificações no servidor (exclusividade do nome de usuário e validade do cupom), use setCustomValidity após a resposta assíncrona: const ok = await checkUsername(value); input.setCustomValidity(ok ? "" : "Already taken");. O navegador identifica imediatamente o novo estado de validade.

Para usar sua própria exibição de erros e ainda obter o acompanhamento da validade, escute o evento invalid e chame e.preventDefault() para suprimir a dica de ferramenta nativa: input.addEventListener("invalid", (e) => { e.preventDefault(); showError(input, input.validationMessage); }).

setCustomValidity aceita apenas uma mensagem personalizada por vez. Para impor várias regras, verifique cada uma e chame setCustomValidity com a mensagem mais relevante, seguindo uma ordem de prioridade. A primeira regra que falhar será exibida.

Se você definir uma mensagem personalizada para um campo obrigatório vazio, sua mensagem e a mensagem padrão poderão entrar em conflito. Escolha uma abordagem por campo: desative a restrição integrada (use type="text" em vez de type="email" e valide por meio de setCustomValidity) ou confie totalmente na validação integrada.

Para validação entre campos (como a confirmação de senha), aplique setCustomValidity ao campo relacionado: confirmInput.setCustomValidity(confirmInput.value === passInput.value ? "" : "Passwords do not match"). O formulário permanecerá inválido até que os dois valores coincidam.

As mensagens integradas são localizadas pelo navegador com base no idioma do usuário. Você deve fornecer no idioma correto as mensagens personalizadas definidas por setCustomValidity — leia navigator.language ou seu próprio estado de i18n e forneça a tradução correspondente.

Abra o DevTools e experimente todos os caminhos inválidos: envio vazio, entrada incompleta, formato incompatível e falha assíncrona. Verifique se a mensagem correta é exibida, se a correção do problema a remove e se o envio de um formulário válido prossegue. Casos-limite, como colar um formato inválido ou usar o preenchimento automático do navegador, merecem testes específicos.

Depois de chamar input.setCustomValidity("Already taken"), como informar ao navegador que o campo de entrada voltou a ser válido?

reportValidity aciona a interface de validação integrada do navegador (foco e dica de ferramenta), sendo ideal para verificações programáticas. setCustomValidity substitui as mensagens padrão pelo seu texto — limpe-a com uma string vazia quando o valor voltar a ser válido. Escute o evento invalid com preventDefault para exibir erros de forma totalmente personalizada. Use-o para validação entre campos, verificações assíncronas e mensagens personalizadas localizadas.