Form Error Summary

Demo & usage

More examples

<sv-form-error-summary [errors]="errors()" (errorActivated)="reveal($event)" />

reveal(e: SvFormError): void {
  if (e.groupId === 'billing') this.billingOpen.set(true);
}

readonly errors = computed<SvFormError[]>(() => {
  if (!this.submitted()) return [];
  const out: SvFormError[] = [];
  if (!this.name().trim()) out.push({ fieldId: 'name', label: 'Full name', message: 'Enter your name' });
  if (!this.postcode().trim()) {
    out.push({ fieldId: 'postcode', label: 'Postcode', message: 'Enter a postcode', groupId: 'billing' });
  }
  return out;
});

<sv-form-error-summary [errors]="errors()" [busy]="submitting()" />

async submit(): Promise<void> {
  this.submitting.set(true);
  const rejected = await this.api.pay(this.form.value);   // 402
  this.serverErrors.set(
    rejected ? [{ label: 'Payment', message: 'Your card was declined' }] : [],
  );
  this.submitting.set(false);   // the summary speaks now, once
}

@ViewChild(SvFormErrorSummaryComponent) summary!: SvFormErrorSummaryComponent;

submit(): void {
  this.submitted.set(true);
  this.summary.focusSummary();   // safe to call blind — a no-op with no errors
}

When to use

• Any form long enough that an invalid field can be off-screen — which in practice is most forms past about six fields.
• Any form with collapsible groups, wizard steps or tabs, where a field can be invalid AND not rendered. This is the case a per-field message alone cannot cover.
• A short, always-visible form does not need one. Two fields both on screen with their own messages are already reachable, and a summary above them is a second copy of what is already said.

Async states

None — this component has nothing to load, so it has no loading, empty or error state to drive.

Outputs

Customization & theming

• `heading` overrides the wording, with `{n}` substituted for the count; the default pluralises between "There is a problem" and "There are N problems".
• `headingLevel` (2–4) places it in the page outline — it renders a real heading element, not a styled div.
• `autoFocus` (on by default) moves focus here when the summary appears; `focusSummary()` does it on demand for a repeat submit.
• `customClass` adds classes to the region.
• `busy` marks the list as being rechecked: `aria-busy` on the region, a `busyMessage` note (default "Rechecking…"), and every announcement held until the recheck lands.
• An entry with no `fieldId` is a submission-level problem — rendered as text, counted in the heading, and never a jump that could fail.

Best practices

• Do: Word `label` exactly as the user sees it above the field. `contact.email` tells a reader nothing about which of the two email fields is wrong, and a summary that cannot be matched to a field by eye is a list of complaints rather than a way in.
• Do: Use the same `message` the field itself shows. Two wordings for one problem read as two problems.
• Do: Handle `(errorActivated)` whenever a field can be hidden — it is the only moment the host gets to open the group before focus is attempted.
• Do: Pass errors in reading order, and only after a submit attempt.
• Do: Leave `fieldId` off a problem that is not a field's — a declined card, an expired session, a form already submitted. The alternative hosts reached for was inventing an id, which turns the entry into a link that reports "(could not jump to this field)" and tells the user the page is broken on top of the error they already have.
• Do: Set `[busy]` while an async validator or a server round-trip is in flight. What is on screen during a submit is the LAST attempt's verdict, and a summary that asserts it is stating something it does not currently know.
• Don't: Don't reach for an `<a href="#field-id">` instead. An anchor can only reach an element that is in the DOM, and the fields this component exists for are exactly the ones that are not.
• Tip: Log `(reachFailed)`. It fires when nothing has that `fieldId` even after the reveal, which is almost always a typo in the id — and the entry says so on screen rather than doing nothing.

Accessibility

• A documented WCAG technique (G139, and the error-identification half of 3.3.1) rather than an invention: the list at the top of the form, each entry linking to its field.
• It is a focusable region (`tabindex="-1"`) named by its own heading, NOT a `role="alert"`. An alert interrupts, and this list changes on every submit — the reader would get the whole thing re-announced over the top of the field they had just reached. Focus arrives once instead, announcing the heading and the count, and the reader moves through at their own pace.
• Entries are buttons, not anchors, because the fields worth linking to are the ones not currently in the DOM. `(errorActivated)` fires first so the host can reveal the field, and focus is attempted on the next frame.
• A target that is not itself focusable — a `<fieldset>` holding a required radio group, say — falls through to the first focusable control inside it. Sending the user to the group and leaving focus on `<body>` would be the same silent nothing the component exists to prevent.
• Focus uses `preventScroll` and then centres the field deliberately, so it arrives with its label and its message both visible rather than scrolled twice to the nearest edge.
• A list that CHANGES while the reader is elsewhere on the page is announced politely through the kit's one announcer — a server error joining a list already on screen was otherwise known only to someone looking at it. The announcement and the focus move are exclusive (focusing the region already reads the heading and the count), a burst of async validators supersedes itself under one key rather than queueing counts the user has passed, and a change that does not change the count says nothing.
• An entry whose field could not be reached says so, and emits `(reachFailed)`. Silence there is worse than no summary: the user has been told where the problem is and that they cannot go to it, with no way to tell a broken link from a field that is merely off-screen.