Skip to content

Error summary

After a failed submit, a titled list of links to every field in error at the top of the form.

<form class="cap-field-options" id="es-static" method="post" action="#saved" aria-labelledby="s-shown">
  <div class="cap-error-summary" data-cap="error-summary" tabindex="-1" role="alert" aria-labelledby="es-static-t">
    <h3 class="cap-error-summary-title" id="es-static-t">There is a problem</h3>
    <ul class="cap-error-summary-list">
      <li><a href="#es-name">Give the job a name, such as Nightly backup.</a></li>
      <li><a href="#es-every-1">Choose how often it runs.</a></li>
    </ul>
  </div>
  <div class="cap-field" data-invalid="true">
    <label class="cap-field-label" for="es-name">Job name</label>
    <input class="cap-input" id="es-name" name="name" aria-invalid="true" aria-describedby="es-name-e" autocomplete="off" />
    <p class="cap-field-error" id="es-name-e">Give the job a name, such as Nightly backup.</p>
  </div>
  <fieldset class="cap-field" data-invalid="true">
    <legend class="cap-field-label">Runs every</legend>
    <div class="cap-field-options">
      <label class="cap-check"><input type="radio" name="every" id="es-every-1" value="hour" aria-invalid="true" aria-describedby="es-every-e" /> Hour</label>
      <label class="cap-check"><input type="radio" name="every" value="day" aria-invalid="true" aria-describedby="es-every-e" /> Day</label>
    </div>
    <p class="cap-field-error" id="es-every-e">Choose how often it runs.</p>
  </fieldset>
</form>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/error-summary.css";
import { enhance } from "capsomer/behavior/error-summary";

enhance();

Usage

<form data-cap="field" method="post">
  <div class="cap-error-summary" data-cap="error-summary" tabindex="-1" role="alert" aria-labelledby="es-t" autofocus>
    <h2 class="cap-error-summary-title" id="es-t">There is a problem</h2>
    <ul class="cap-error-summary-list">
      <li><a href="#name">Give the job a name, such as Nightly backup.</a></li>
      <li><a href="#every-hour">Choose how often it runs.</a></li>
    </ul>
  </div>
  ...the fields, each with the same message beside it...
</form>
import { ErrorSummary } from "capsomer/react/error-summary";
<form onSubmit={check}>
  <ErrorSummary errors={[{ id: "name", text: "Give the job a name, such as Nightly backup." }]} />
  ...
</form>

Examples

A live form: send it empty

<form class="cap-field-options" id="es-live" data-cap="field" action="#added" aria-labelledby="s-live">
  <div class="cap-field">
    <label class="cap-field-label" for="es-site">Site name <span class="cap-field-required" aria-hidden="true">Required</span></label>
    <input class="cap-input" id="es-site" name="site" required autocomplete="off" aria-describedby="es-site-e" data-error-value-missing="Give the site a name, such as Field notes." />
    <p class="cap-field-error" id="es-site-e" hidden></p>
  </div>
  <div class="cap-field">
    <label class="cap-field-label" for="es-email">Owner's email <span class="cap-field-required" aria-hidden="true">Required</span></label>
    <input class="cap-input" id="es-email" name="email" type="email" required autocomplete="email" spellcheck="false" aria-describedby="es-email-e" data-error-value-missing="Enter the owner's email, such as maya.chen@example.edu." data-error-type-mismatch="Enter an email address with an @, such as maya.chen@example.edu." />
    <p class="cap-field-error" id="es-email-e" hidden></p>
  </div>
  <div><button type="submit" class="cap-btn" data-variant="primary">Add site</button></div>
  <p class="cap-muted" id="es-result"></p>
</form>

API reference

ErrorSummary

PropTypeRequiredDoes
errorsArray<{ id: string; text: ReactNode }>YesOne per field in error: the control's id and the same words as the message beside it.
titleReactNode

Functions

FunctionSignatureDoes
setTitleError(on: boolean): voidPuts "Error: " at the start of the page title, or takes it off.
focusTarget(target: HTMLElement): HTMLElementWhere a link to a field lands. A control is itself. A group (a fieldset, a repeater, a date input) lands on the control in it that is in error, else the first one left empty, else its first control, so the person is put where the answer goes, not on the group's edge.
wireSummary(summary: HTMLElement): () => void
summaryFor(form: HTMLFormElement): HTMLElementThe form's own .cap-error-summary, or a new one made as its first child.
showSummary(summary: HTMLElement, items: SummaryItem[]): voidLists the fields in error, each a link with the message beside its field, and moves focus to the summary.
hideSummary(summary: HTMLElement): void
enhance(root?: ParentNode): () => voidWires every [data-cap="error-summary"] under root not yet wired (one the server rendered).

Parts and data attributes

ClassIs
.cap-error-summarythe root
.cap-error-summary-lista part
.cap-error-summary-titlea part
StateRead from
:focusthe platform
[hidden]an attribute

Accessibility

KeyDoes
(a submit finds two or more fields in error)Focus moves to the summary; its title and links are read
TabMoves through the links, then on into the form
Enter on a linkPuts focus in that field, with its label in view; a link to a group (a fieldset, a repeater) lands on its control in error, else its first empty one (focusTarget)
  • role="alert", tabindex="-1" and aria-labelledby its title: announced as it appears and named "There is a problem".
  • The title is an h2 (an h3 where the form sits under an h2).
  • Each link is at least --target high; links are --crit on the surface, semibold, at 4.5:1 in both themes.
  • Forced colors: the edge is CanvasText and the links LinkText.
  • No motion.