Forms

const form =
  document.querySelector<HTMLFormElement>("#signup");
if (!form) throw new Error("#signup not found");
 
document.forms.namedItem("signup"); // by name or id
input.form; // owner form: HTMLFormElement | null

interface SignupControls extends HTMLFormControlsCollection {
  email: HTMLInputElement;
  password: HTMLInputElement;
  plan: RadioNodeList; // several radios, one name
  terms: HTMLInputElement;
}
 
interface SignupForm extends HTMLFormElement {
  readonly elements: SignupControls;
}
 
const form = document.querySelector<SignupForm>("#signup");
form?.elements.email.value; // string
form?.elements.plan.value;  // checked radio's value, or ""

function control<T extends Element>(
  form: HTMLFormElement,
  name: string,
  type: { new (): T; readonly name: string },
): T {
  const el = form.elements.namedItem(name);
  if (!(el instanceof type)) {
    throw new TypeError(`"${name}" is not ${type.name}`);
  }
  return el;
}
 
const email = control(form, "email", HTMLInputElement);
const bio = control(form, "bio", HTMLTextAreaElement);

<form id="search" action="/search"></form>
 
<!-- elsewhere in the page -->
<input name="q" form="search" />
<button form="search">Search</button>

form.addEventListener("submit", (event) => {
  event.preventDefault();
  // include the clicked button's name=value pair
  const data = new FormData(form, event.submitter);
 
  data.get("email");  // FormDataEntryValue | null
  data.getAll("tag"); // FormDataEntryValue[]
  data.has("terms");  // boolean
});

const raw = Object.fromEntries(new FormData(form));
// { [k: string]: FormDataEntryValue }

import { z } from "zod";
 
export const Signup = z.object({
  email: z.email(),
  age: z.coerce.number().int().min(13),
  plan: z.enum(["free", "pro"]),
  tags: z.array(z.string()).max(5),
  newsletter: z.boolean(),
  terms: z.literal("on", { error: "Accept the terms" }),
});
export type Signup = z.infer<typeof Signup>;
 
export function readSignup(data: FormData) {
  return Signup.safeParse({
    ...Object.fromEntries(data),
    tags: data.getAll("tags"),
    newsletter: data.has("newsletter"),
  });
}

const result = readSignup(new FormData(form));
if (result.success) {
  result.data.age; // number
} else {
  const { fieldErrors } = z.flattenError(result.error);
  fieldErrors.email; // string[] | undefined
}

const qty = control(form, "qty", HTMLInputElement);
const n = qty.valueAsNumber;
if (Number.isNaN(n)) throw new Error("not a number");
 
const due = control(form, "due", HTMLInputElement); // date
due.valueAsDate; // Date at 00:00 UTC, or null when empty
due.valueAsDate?.toISOString().slice(0, 10); // "2026-09-25"

const terms = control(form, "terms", HTMLInputElement);
terms.checked; // boolean, the state
terms.value;   // "on" unless value="..." is set
 
const data = new FormData(form);
data.has("terms");       // true only when checked
// every checked box named "toppings"
data.getAll("toppings");

function syncConfirm(
  password: HTMLInputElement,
  repeat: HTMLInputElement,
): void {
  const same = repeat.value === password.value;
  repeat.setCustomValidity(same ? "" : "Passwords differ");
}
 
const password = control(form, "password", HTMLInputElement);
const repeat = control(form, "repeat", HTMLInputElement);
for (const el of [password, repeat]) {
  el.addEventListener("input", () => {
    syncConfirm(password, repeat);
  });
}

form.noValidate = true;
form.addEventListener("submit", (event) => {
  if (!form.checkValidity()) {
    event.preventDefault();
    focusFirstInvalid(form); // see Accessibility
  }
});
 
// `invalid` does not bubble: listen in the capture phase
form.addEventListener("invalid", (event) => {
  const el = event.target;
  if (el instanceof HTMLInputElement) {
    showFieldError(el, el.validationMessage);
  }
}, true);

form.addEventListener("submit", (event) => {
  event.preventDefault();       // stop the page navigation
  event.submitter;              // HTMLElement | null
});

async function post(form: HTMLFormElement, data: FormData) {
  // multipart, files included
  await fetch(form.action, { method: "POST", body: data });
 
  // urlencoded, strings only
  await fetch(form.action, {
    method: "POST",
    body: toParams(data),
  });
 
  // JSON: set the header yourself
  await fetch("/api/signup", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(Object.fromEntries(data)),
  });
}
 
// URLSearchParams(formData) fails to type-check: File values
function toParams(data: FormData): URLSearchParams {
  const params = new URLSearchParams();
  for (const [key, value] of data) {
    if (typeof value === "string") params.append(key, value);
  }
  return params;
}

async function onSubmit(event: SubmitEvent): Promise<void> {
  event.preventDefault();
  const form = event.currentTarget;
  if (!(form instanceof HTMLFormElement)) return;
  if (form.ariaBusy === "true") return; // double submit
 
  const button = event.submitter;
  // before disabling
  const data = new FormData(form, button);
  const btn =
    button instanceof HTMLButtonElement ? button : null;
  if (btn) btn.disabled = true;
  form.ariaBusy = "true";
  try {
    const res = await fetch(form.action, {
      method: "POST",
      body: data,
    });
    if (!res.ok) throw new Error(`HTTP ${res.status}`);
    form.reset();
  } catch (error) {
    showFormError(form, error);
  } finally {
    if (btn) btn.disabled = false;
    form.ariaBusy = null;
  }
}
 
form.addEventListener("submit", onSubmit);

<input
  type="file"
  name="photos"
  accept="image/png,image/jpeg"
  multiple
/>

const input = control(form, "photos", HTMLInputElement);
input.addEventListener("change", async () => {
  const files = Array.from(input.files ?? []);
  for (const file of files) {
    file.name;         // "cat.png", no path
    file.size;         // bytes
    file.type;         // "image/png", from the extension
    file.lastModified; // ms since epoch
  }
  const first = files[0];
  if (first?.type === "text/csv") {
    const text = await first.text();
    text.split("\n").length;
  }
});

const MAX_BYTES = 5 * 1024 * 1024;
 
function checkImage(file: File): string | null {
  if (!file.type.startsWith("image/")) return "Not an image";
  if (file.size > MAX_BYTES) return "Larger than 5 MB";
  return null;
}

function preview(file: File, img: HTMLImageElement): void {
  const url = URL.createObjectURL(file);
  img.addEventListener(
    "load",
    () => URL.revokeObjectURL(url),
    { once: true },
  );
  img.src = url;
}

function upload(
  url: string,
  body: FormData,
  onProgress: (fraction: number) => void,
): Promise<number> {
  return new Promise((resolve, reject) => {
    const xhr = new XMLHttpRequest();
    xhr.open("POST", url);
    xhr.upload.addEventListener("progress", (e) => {
      if (e.lengthComputable) onProgress(e.loaded / e.total);
    });
    xhr.addEventListener("load", () => resolve(xhr.status));
    xhr.addEventListener("error", () => {
      reject(new Error("Network error"));
    });
    xhr.send(body);
  });
}
 
const body = new FormData();
for (const file of files) {
  body.append("photos", file, file.name);
}
await upload("/api/photos", body, (f) => {
  bar.value = f;
});

<label for="email">Email</label>
<input id="email" name="email" type="email" required
  autocomplete="email"
  aria-describedby="email-hint email-error" />
<p id="email-hint">Used for receipts only.</p>
<p id="email-error" hidden></p>
 
<fieldset>
  <legend>Plan</legend>
  <label>
    <input type="radio" name="plan" value="free" /> Free
  </label>
  <label>
    <input type="radio" name="plan" value="pro" /> Pro
  </label>
</fieldset>

type Control =
  | HTMLInputElement
  | HTMLSelectElement
  | HTMLTextAreaElement;
 
function isControl(el: Element): el is Control {
  return (
    el instanceof HTMLInputElement ||
    el instanceof HTMLSelectElement ||
    el instanceof HTMLTextAreaElement
  );
}
 
function showFieldError(el: Control, message: string): void {
  const out = document.getElementById(`${el.id}-error`);
  if (out) {
    out.textContent = message; // never innerHTML
    out.hidden = message === "";
  }
  el.ariaInvalid = message === "" ? null : "true";
}
 
function focusFirstInvalid(form: HTMLFormElement): void {
  const first = Array.from(form.elements)
    .filter(isControl)
    .find((el) => !el.validity.valid);
  first?.focus();
}

import { Signup } from "./signup-schema";
 
export async function POST(req: Request): Promise<Response> {
  const data = await req.formData();
  const result = Signup.safeParse({
    ...Object.fromEntries(data),
    tags: data.getAll("tags"),
    newsletter: data.has("newsletter"),
  });
  if (!result.success) {
    return Response.json(
      { error: "Invalid input" },
      { status: 422 },
    );
  }
  // result.data is typed and trusted from here on
  return Response.json({ ok: true }, { status: 201 });
}