HTML
Cómo construye el navegador el conjunto de datos de un formulario, qué controles participan y cómo leer o modificar valores mediante FormData.
representa las entradas que un formulario enviaría y permite leer, añadir o transportar pares nombre/valor desde JavaScript.
FormDataconst formData = new FormData(form);<form id="profile-form">
<input name="name" value="Nicolás">
<input name="avatar" type="file">
</form>const form = document.querySelector("#profile-form");
const formData = new FormData(form);Solo incluye controles exitosos y asociados.
<input id="email" type="email" value="hello@example.com">No aparece en FormData sin name.
const name = formData.get("name");Retorna el primer valor o null.
El resultado puede ser string | File | null. No lo conviertas directamente a número u objeto sin validar.
const technologies = formData.getAll("technology");Obtiene todas las entradas repetidas, por ejemplo varios checkboxes.
formData.has("newsletter");Ayuda a distinguir ausencia. Un checkbox no seleccionado normalmente no aparece.
formData.append("tag", "html");
formData.append("tag", "accessibility");append conserva valores existentes.
formData.set("name", "Nicolás Garzón");set reemplaza entradas previas del mismo nombre.
formData.delete("internalField");Elimina todas las entradas con ese name.
for (const [name, value] of formData) {
console.log(name, value);
}No registres passwords, tokens o archivos sensibles en consola o analytics.
form.addEventListener("submit", (event) => {
event.preventDefault();
const data = new FormData(form, event.submitter);
});Cuando la API soporta el segundo argumento, incluye name/value del botón submitter. Sin él, una construcción manual puede perder la intención publish o draft.
form.addEventListener("formdata", (event) => {
event.formData.append("clientVersion", "1");
});Permite ajustar el conjunto cuando se construye para envío.
No añadas datos de autoridad que el servidor debería determinar por sesión o permisos.
await fetch(form.action, {
method: form.method,
body: new FormData(form),
});No configures manualmente Content-Type: multipart/form-data; el navegador añade el boundary.
const object = Object.fromEntries(formData);Pierde valores repetidos porque las claves se sobrescriben. Tampoco transforma tipos ni representa archivos como JSON útil.
Para checkboxes:
const tags = formData.getAll("tag");const quantityValue = formData.get("quantity");Aunque provenga de input type="number", es normalmente string.
const quantity = Number(quantityValue);Debes comprobar vacío, finitud, rango e integralidad según la regla.
Checkbox:
const subscribed = formData.has("newsletter");const attachment = formData.get("attachment");
if (attachment instanceof File && attachment.size > 0) {
// validar antes de enviar/procesar
}El cliente puede ofrecer feedback, pero el servidor valida tipo, contenido y tamaño.
<form id="order-form"></form>
<input form="order-form" name="notes">FormData incluye controles con el mismo form owner aunque estén fuera del árbol descendiente.
No habilites temporalmente controles disabled solo para capturar valores que el servidor debería conocer por otra fuente.
Form-associated custom elements pueden participar mediante ElementInternals cuando se implementan correctamente. No basta con tener un atributo name en cualquier custom element.
Para datos exclusivamente textuales compatibles con URL encoding:
const params = new URLSearchParams(formData);No es apropiado cuando existen archivos y puede convertir valores de formas inesperadas. Comprueba el conjunto antes.
form.addEventListener("submit", async (event) => {
event.preventDefault();
if (!form.reportValidity()) return;
const formData = new FormData(form, event.submitter);
const response = await fetch(form.action, {
method: "POST",
body: formData,
});
if (!response.ok) {
showSubmissionError();
}
});El servidor sigue siendo la autoridad.
¿Por qué Object.fromEntries(new FormData(form)) puede perder checkboxes seleccionados?
Porque varios checkboxes pueden compartir el mismo name; un objeto solo conserva una propiedad por clave y sobrescribe valores anteriores.
Seguridad y privacidad en formularios analiza datos no confiables, CSRF, uploads y información sensible.