# Inline vs Modal Error Delivery: Choosing Between Them

Deciding whether a validation failure should render beside its field or interrupt the flow inside a dialog is a per-error architectural choice, not a stylistic one, and getting it wrong forces users to hunt for the problem or blocks them from fixing it; this page defines the decision rule and shows both patterns driven from the same Constraint Validation API baseline.

# When to Use This Field-Anchored vs Dialog-Interrupt Approach

Inline delivery attaches each message to the control that produced it, so the fix is one saccade away from the message. Modal delivery pulls a single blocking dialog over the viewport, seizing focus until acknowledged. Choose deliberately:

• Reach for inline when the error maps to exactly one field, the user can correct it in place, and multiple fields may fail at once (a signup form). This is the default for field-level constraint failures.
• Reach for a modal when the failure is form-global, destructive, or requires a decision before the form can continue — a submit that would overwrite server state, or a confirmation gate. Modals are for stopping, not for annotating.
• If the message is transient and non-blocking (a background autosave failed), neither fits — prefer a toast, covered in When to Use a Toast vs an Inline Error.

The rule of thumb: inline scales to N simultaneous field errors; a modal must represent exactly one decision. If you find yourself listing five field errors inside a dialog, you wanted inline.

# checkValidity() + reportValidity() Baseline for Both Deliveries

Both patterns share one source of truth: a <form novalidate> whose validity you read manually. Suppress the browser’s native bubbles, then route the collected failures to whichever delivery the situation calls for.

// HTML: <form id="signup" novalidate> ... </form>
const form = document.querySelector<HTMLFormElement>("#signup")!;

// One manual gate. novalidate stops native bubbles; we own rendering.
form.addEventListener("submit", (event: SubmitEvent) => {
  event.preventDefault();

  // Collect every invalid control up front so we can decide inline vs modal.
  const invalid = [...form.elements].filter(
    (el): el is HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement =>
      "validity" in el && !(el as HTMLInputElement).checkValidity(),
  );

  if (invalid.length === 0) {
    submitConfirmed(form); // may raise a modal for destructive confirmation
    return;
  }

  // N field-level failures -> inline, anchored to each control.
  clearInlineErrors(form);
  for (const field of invalid) renderInlineError(field);

  // Move focus to the first offender (see focus-management guidance).
  invalid[0].focus();
});

function renderInlineError(field: HTMLElement & { validationMessage: string }) {
  const msg = document.createElement("p");
  msg.id = `${field.id}-error`;
  msg.className = "field-error";
  msg.role = "alert"; // polite-by-default live region for the message
  msg.textContent = field.validationMessage; // or a custom validity message
  field.setAttribute("aria-invalid", "true");
  field.setAttribute("aria-describedby", msg.id);
  field.insertAdjacentElement("afterend", msg);
}

function clearInlineErrors(form: HTMLFormElement) {
  form.querySelectorAll(".field-error").forEach((n) => n.remove());
  form.querySelectorAll("[aria-invalid]").forEach((el) => {
    el.removeAttribute("aria-invalid");
    el.removeAttribute("aria-describedby");
  });
}

// Modal path: exactly one decision, focus-trapped, dismiss returns to trigger.
function submitConfirmed(form: HTMLFormElement) {
  const dialog = document.querySelector<HTMLDialogElement>("#confirm-dialog")!;
  dialog.returnValue = "";
  dialog.showModal(); // native focus trap + inert background
  dialog.addEventListener(
    "close",
    () => {
      if (dialog.returnValue === "confirm") form.submit();
    },
    { once: true },
  );
}

The single checkValidity() loop keeps the two deliveries from drifting apart: the same validity state decides both. Use reportValidity() only if you want the native bubble as a fallback; the manual render above replaces it.

# Delivery Configuration: Option Reference

These are the values you tune per recipe when wiring the two paths above.

# Verification Steps

• Submit an empty required field: an inline .field-error node appears immediately after the control, and no native bubble shows.
• Inspect the field in DevTools: it carries aria-invalid="true" and aria-describedby pointing at the message id.
• Trigger three failures at once: three inline nodes render and focus lands on the first invalid control.
• Open the confirm modal: Tab cycles only inside the dialog (focus trap holds), and Escape closes it returning focus to the trigger.
• A screen reader announces the first inline error via its role="alert" live region.

import { test, expect } from "@playwright/test";

test("field errors deliver inline, confirmation delivers modal", async ({ page }) => {
  await page.goto("/signup");
  await page.getByRole("button", { name: "Create account" }).click();

  const emailError = page.locator("#email-error");
  await expect(emailError).toBeVisible();
  await expect(page.locator("#email")).toHaveAttribute("aria-invalid", "true");
  // No native bubble competes with our inline node.
  await expect(page.locator("#email")).toBeFocused();

  await page.getByLabel("Email").fill("dev@example.com");
  await page.getByLabel("Password").fill("hunter2hunter2");
  await page.getByRole("button", { name: "Create account" }).click();
  // Valid form escalates to the single blocking decision.
  await expect(page.getByRole("dialog")).toBeVisible();
});

# Edge Cases & Failure Modes

Modal as an error dump. Piling several field errors into one dialog forces the user to memorise the list, dismiss the modal, then find each field blind. Fix: only ever put a single form-global decision in a modal; route field-level failures inline, where accessible error messaging can anchor each message to its control.

Focus lost after inline render. If you render inline nodes but leave focus on the submit button, keyboard and screen-reader users never reach the first error. Fix: call .focus() on the first invalid control after rendering, per focus management after a failed submit.

Async failure delivered before it resolves. When validity depends on asynchronous server checks (a uniqueness probe), synchronous checkValidity() passes and the modal opens prematurely. Fix: await the async result and set setCustomValidity() before the submit gate runs, so the field reports invalid inline instead of the modal firing on stale state.

# Escalating From Inline to Modal on Repeated Failure

The two deliveries are not mutually exclusive across a session — they form a ladder. Start every field-level constraint failure inline, but track how many times a submit has been attempted against an unchanged, still-invalid form. After a threshold, a form-global modal that names the blocking condition and offers a recovery route (contact support, reset the form, switch payment method) is justified: the inline messages have demonstrably failed to unblock the user, so a single deliberate interrupt is now the lower-friction option.

The mechanism is a counter that only advances when the same set of fields fails again, so genuine progress resets it. Do not escalate on the first failure — an unsolicited modal on attempt one trains users to dismiss dialogs reflexively, which then swallows the one modal that carries a real destructive decision.

// Escalation state lives outside the handler so it survives re-submits.
let sameFailureStreak = 0;
let lastFailureSignature = "";

function signatureOf(fields: readonly HTMLElement[]): string {
  // A stable fingerprint of *which* controls failed, order-independent.
  return fields
    .map((f) => (f as HTMLInputElement).name)
    .sort()
    .join("|");
}

function deliverFailures(
  form: HTMLFormElement,
  invalid: readonly (HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement)[],
) {
  const signature = signatureOf(invalid);

  // Only advance the streak when the identical field set fails again.
  sameFailureStreak = signature === lastFailureSignature ? sameFailureStreak + 1 : 1;
  lastFailureSignature = signature;

  clearInlineErrors(form);
  for (const field of invalid) renderInlineError(field);
  invalid[0].focus();

  // Third identical failure: the inline path has not worked. Interrupt once.
  if (sameFailureStreak >= 3) {
    openRecoveryModal(invalid.length);
    sameFailureStreak = 0; // reset so we do not nag on every subsequent submit
  }
}

Keeping the escalation state module-scoped rather than inside the submit listener is what lets the streak survive across attempts. Reset both counters after a successful submit so a later, unrelated failure starts the ladder from the bottom.

# Preserving Scroll and Focus Context Across the Interrupt

A modal’s showModal() renders the backdrop inert, which is exactly why it is safe for a single decision but hostile as an error list: the fields the user must fix are behind an uninteractable veil. When you do open a modal after inline delivery, capture the scroll position and the active element first, because the browser restores neither for you once the dialog closes.

function openRecoveryModal(failedCount: number) {
  const dialog = document.querySelector<HTMLDialogElement>("#recovery-dialog")!;
  const returnTarget = document.activeElement as HTMLElement | null;
  const scrollY = window.scrollY;

  dialog.querySelector<HTMLElement>("[data-count]")!.textContent = String(failedCount);
  dialog.showModal();

  dialog.addEventListener(
    "close",
    () => {
      window.scrollTo({ top: scrollY }); // showModal can shift layout on some engines
      returnTarget?.focus({ preventScroll: true }); // return focus to the trigger
    },
    { once: true },
  );
}

Returning focus to returnTarget rather than to document.body is the difference between a keyboard user resuming where they left off and being dumped at the top of the document. This mirrors the guidance in managing focus after a failed submit: every delivery surface owns its own focus-restoration contract, and the modal’s is the strictest because it stole focus in the first place.

# Related Guides

• Inline vs Toast vs Modal Error Delivery — the parent comparison that positions all three delivery surfaces.
• When to Use a Toast vs an Inline Error — the sibling decision for non-blocking transient messages.
• Managing Focus After Validation Failure — where to move focus once either delivery renders.
• Inline Error Messaging Strategies — anchoring, wording, and live-region details for the inline path.
• Designing Accessible Error Toast Notifications — the accessible pattern for the third surface neither inline nor modal covers.

← Back to Error Delivery Comparison