CKTIS / JavaScript
HTMLInputElement.setCustomValidity — um erro de validação personalizado
HTMLInputElement.setCustomValidity define ou limpa o erro personalizado de um campo de formulário. Uma cadeia vazia limpa esse erro, mas não desativa outras restrições.
Versão: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support
Sintaxe
input.setCustomValidity(message)HTMLInputElement.setCustomValidity é um método da API de validação de formulários do navegador, definido pelo HTML Living Standard e não pelo ECMAScript. É suportado pelos motores de navegador atuais; a presença do Node 24 não comprova a disponibilidade desta API.
Ao chamar input.setCustomValidity(message) com uma cadeia não vazia, input.validity.customError passa a true. Passar "" limpa apenas o erro personalizado: restrições como required continuam a aplicar-se. O método devolve undefined, não um resultado de validação.
O método não apresenta uma mensagem por si só. checkValidity() verifica a validade sem apresentar indicações de erro. Se o campo não passar na validação, reportValidity() devolve false e o navegador só comunica o problema ao utilizador se o evento invalid não for cancelado. Cancelar o evento não altera o valor devolvido. Os elementos excluídos da validação podem manter um erro personalizado, embora não impeçam o envio validado de um formulário.
Depois de alterar um valor, volta a calcular a regra e limpa explicitamente qualquer erro desatualizado, normalmente num processador do evento input. No exemplo, o false false final significa que não existe um erro personalizado, mas que required não está satisfeito. A validação do lado do cliente não substitui a validação do lado do servidor.
Exemplos
const input = document.createElement("input");
input.required = true;
input.value = "admin";
function validate() {
input.setCustomValidity(
input.value === "admin" ? "Reserved name." : ""
);
}
validate();
console.log(input.validity.customError, input.checkValidity());
input.value = "alex";
validate();
console.log(input.validity.customError, input.checkValidity());
input.value = "";
validate();
console.log(input.validity.customError, input.checkValidity());Resultado
true false false true false false
O código apresentado e o resultado declarado foram verificados num ambiente isolado pelo método registado na prova de verificação desta versão exata.