Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / JavaScript

HTMLInputElement.setCustomValidity — un error de validación personalizado

HTMLInputElement.setCustomValidity establece o borra el error personalizado de un campo de formulario. Una cadena vacía borra ese error, pero no desactiva otras restricciones.

Versión: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Sintaxis

input.setCustomValidity(message)

HTMLInputElement.setCustomValidity es un método de la API de validación de formularios del navegador, definido por el HTML Living Standard y no por ECMAScript. Es compatible con los motores de navegador actuales; la presencia de Node 24 no demuestra que esta API esté disponible.

Al llamar a input.setCustomValidity(message) con una cadena no vacía, input.validity.customError pasa a ser true. Pasar "" borra únicamente el error personalizado: las restricciones como required siguen aplicándose. El método devuelve undefined, no un resultado de validación.

El método no muestra ningún mensaje por sí solo. checkValidity() comprueba la validez sin mostrar indicaciones de error. Si el campo no supera la validación, reportValidity() devuelve false y el navegador solo informa del problema al usuario si no se cancela el evento invalid. Cancelar el evento no cambia el valor devuelto. Los elementos excluidos de la validación pueden conservar un error personalizado aunque no impidan el envío validado de un formulario.

Después de cambiar un valor, vuelve a calcular la regla y borra explícitamente cualquier error obsoleto, normalmente en un controlador del evento input. En el ejemplo, el false false final significa que no hay un error personalizado, pero required sigue sin cumplirse. La validación del lado del cliente no sustituye a la validación del lado del servidor.

Ejemplos

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

El código mostrado y el resultado declarado se verificaron en un entorno aislado mediante el método registrado en la evidencia de verificación de esta versión exacta.

Fuentes