# Building an Accessible Error Summary

When a form fails validation with several problems, how does a user learn how many there are, what they are, and how to get to each one? Inline messages beside each field answer “what is wrong here?” but not “what is wrong overall?”. An error summary — a box at the top of the form that says “There are 3 problems” and links to each field — answers the overall question, and it is the pattern public-sector design systems standardised because it works for screen reader users, keyboard users, people with cognitive disabilities and everyone on a long form. This recipe builds one from the same validity data the Constraint Validation API exposes: collected in document order during checkValidity(), rendered with the same messages as the inline errors, focused on submit, linked so each item moves focus to its field, and rendered server-side as well so it works without JavaScript.

# When to Use an Error Summary

Use a summary on any form where more than one error can occur at once, which is most forms with more than three fields. It matters most for:

• Long forms, where the first error may be off-screen and later ones far below it.
• Server-rendered error pages, where no script moves focus after a reload.
• Screen reader users, who otherwise discover errors one field at a time.
• Forms with group-level errors (a “choose at least one” checkbox set) that have no single input to focus.

For a single error, going straight to the field is often better; the trade-off is discussed in error summary vs inline errors. A summary always complements inline messages — never replaces them — because the user needs the message again when they arrive at the field.

# Minimal Working Error Summary

<form id="permit" novalidate>
  <div class="error-summary" id="error-summary" tabindex="-1" role="alert" aria-labelledby="error-summary-title" hidden>
    <h2 id="error-summary-title">There is a problem</h2>
    <ul class="error-summary-list"></ul>
  </div>
  <!-- fields, each with an id and an #id-err message element -->
</form>

interface Problem { id: string; message: string }

const form = document.querySelector<HTMLFormElement>("#permit")!;
const summary = form.querySelector<HTMLElement>("#error-summary")!;
const title = summary.querySelector<HTMLElement>("#error-summary-title")!;
const list = summary.querySelector<HTMLUListElement>(".error-summary-list")!;
const baseTitle = document.title;

function collectProblems(): Problem[] {
  const seen = new Set<string>();
  const problems: Problem[] = [];
  for (const el of form.elements) {
    if (!(el instanceof HTMLInputElement || el instanceof HTMLSelectElement || el instanceof HTMLTextAreaElement)) continue;
    if (el.validity.valid || !el.willValidate) continue;
    const key = el.type === "radio" || el.type === "checkbox" ? el.name : el.id;   // one entry per group
    if (seen.has(key)) continue;
    seen.add(key);
    problems.push({ id: el.id, message: messageFor(el) });                         // same text as inline
  }
  return problems;
}

function renderSummary(problems: Problem[]): void {
  if (problems.length === 0) {
    summary.hidden = true;
    document.title = baseTitle;
    return;
  }
  title.textContent = problems.length === 1 ? "There is a problem" : `There are ${problems.length} problems`;
  list.replaceChildren(...problems.map((p) => {
    const li = document.createElement("li");
    const a = Object.assign(document.createElement("a"), { href: `#${p.id}`, textContent: p.message });
    a.addEventListener("click", (e) => {
      e.preventDefault();
      const field = document.getElementById(p.id)!;
      const label = document.querySelector<HTMLElement>(`label[for="${p.id}"]`) ?? field.closest("fieldset")?.querySelector("legend");
      (label ?? field).scrollIntoView({ block: "center" });          // show the label, not just the input
      field.focus({ preventScroll: true });
    });
    li.append(a);
    return li;
  }));
  summary.hidden = false;
  document.title = `Error: ${baseTitle}`;
}

form.addEventListener("submit", (event) => {
  event.preventDefault();
  renderInlineErrors();                                  // your existing per-field messages
  const problems = collectProblems();                    // checkValidity-equivalent, in document order
  renderSummary(problems);
  if (problems.length) {
    summary.focus();                                     // user hears "There are 2 problems" first
    return;
  }
  form.submit();
});

Three details distinguish a summary that helps from one that merely exists. The message text is identical to the inline message at each field, so users recognise the problem when they arrive. The link handler scrolls the label into view, not just the input — landing with the label off the top of the screen leaves the user unsure which field they are in. And radio and checkbox groups produce one entry, not one per option.

# Error Summary Option Reference

Using both role="alert" and focus deserves a note: when focus moves to the summary, screen readers read it as the focused element; role="alert" additionally ensures it is announced in the server-rendered case where the page loads with the summary already present and a small script focuses it. Some teams use one or the other; test your combination with the screen readers your users rely on.

# Verification Steps

• Submit an empty form: focus is on the summary, and a screen reader reads “There are 3 problems” followed by the list.
• Activate each summary link: focus moves to the field, with its label visible.
• The text of each summary item matches the message at the field exactly.
• Fix one error and resubmit: the summary updates its count and items.
• Fix everything: the summary disappears and the page title loses its “Error:” prefix.

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

test("summary links move focus to the field with matching text", async ({ page }) => {
  await page.goto("/permit");
  await page.getByRole("button", { name: "Continue" }).click();
  const summary = page.locator("#error-summary");
  await expect(summary).toBeFocused();
  await expect(summary.getByRole("heading")).toHaveText("There are 2 problems");
  await summary.getByRole("link", { name: "Enter your date of birth" }).click();
  await expect(page.getByLabel("Date of birth")).toBeFocused();
  await expect(page.locator("#dob-err")).toHaveText("Enter your date of birth");
});

# Edge Cases and Failure Modes

Summary without inline messages. A summary that lists errors while the fields show nothing forces users to remember the message while navigating. Always show both.

Messages that differ. “Date of birth is required” in the summary and “Enter your date of birth” at the field makes users wonder whether there are two problems. Generate both from one function.

Links that jump to the input, hiding the label. Browsers scroll an anchor target to the top edge, which often hides its label. Handle the click and scroll the label into view, as above.

Errors that are not about a field. “Your session expired” or “This slot was just booked” have no field to link to. List them as plain text items at the top of the summary, or show them in a separate form-level alert above it.

# Keeping the Summary Up to Date

A summary that shows stale problems is worse than none. Decide when it updates and apply the rule consistently. The common approach: rebuild it on every submit attempt, and leave it unchanged while the user edits fields in between — each field’s inline message clears live, but the summary stays as a record of what the last submit found until the user submits again. A livelier alternative removes items as their fields become valid, updating the count; if you do that, do not announce each change, and hide the summary when the last item disappears. Either way, never add new items between submits, which would make the summary grow while the user is fixing things.

# Rendering the Summary on the Server

The summary is most valuable exactly when there is no script to move focus: after a server-rendered error response. Render the same markup on the server from the validation result, with the container already visible, the title prefixed with “Error:”, and a tiny inline script — or the autofocus attribute on the summary where appropriate — to focus it after load. Because the markup is identical, the scripted and server paths look and behave the same, which is the goal of progressive enhancement without JavaScript.

export function renderErrorSummary(problems: Array<{ id: string; message: string }>): string {
  if (!problems.length) return "";
  const heading = problems.length === 1 ? "There is a problem" : `There are ${problems.length} problems`;
  const items = problems.map((p) => `<li><a href="#${p.id}">${escapeHtml(p.message)}</a></li>`).join("");
  return `<div class="error-summary" id="error-summary" tabindex="-1" role="alert" aria-labelledby="error-summary-title">
    <h2 id="error-summary-title">${heading}</h2><ul class="error-summary-list">${items}</ul></div>`;
}

# Related Guides

• Focus Management & Keyboard Navigation — the focus rules the summary follows.
• Error Summary vs Inline Errors — when to use each and how they combine.
• Listening for the invalid Event — collecting failures during validation.
• WCAG 3.3.1 Error Identification Checklist — what the summary helps satisfy.

← Back to Focus Management & Keyboard Navigation