VERIFICATION-0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF
Validation summary
<forma-validation-summary>
Focusable page- or form-level error summary with links back to each affected control.
- Authoring tag
<forma-validation-summary>- Category
- Feedback and status
- Behavior owner
- Application state
- Canonical source
patterns/validation-summary.html
Purpose
A validation summary lists every problem that stopped a form or survey from being submitted, as links to the affected controls. Forma renders a bordered block with a mark, a heading that states the count, and a list of links. The application inserts it after a failed submit, moves focus to it (it carries tabindex="-1" for that purpose), and keeps each link pointing at the id of the control or group it describes. Forma does not collect errors or decide validity.
Use when
- A submit or Continue action found more than one problem, or one problem the user may not see because it is off-screen.
- A long form, survey page or wizard step needs a single place where the user can see everything that needs attention.
- The application moves focus after a failed submit and needs a stable, labelled target.
Avoid when
- Only one visible field is wrong and focus can go straight to it: a Validation message is enough.
- The failure is not caused by the user's input (a server error, conflict or unknown outcome): use Alert, Conflict review or Operation status.
- The list is of outstanding work rather than input errors: use Obligation panel or Readiness checklist.
Behavior to know
- A thick accent border and a secondary surface set it apart from ordinary content; the heading and count carry the meaning.
role="alert"announces it when inserted;tabindex="-1"lets the application focus it without adding it to the Tab order.- Every item is a link, so the whole summary is operable with a keyboard.
Basic example
The smallest correct markup: the canonical pattern from patterns/validation-summary.html inside its public tag. Copy this first, then adapt labels, names and state.
Minimal validation summary
Rendered from the canonical pattern file.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
There are 2 responses to review
<forma-validation-summary class="forma-component-tag">
<div class="forma-validation-summary" role="alert" tabindex="-1" aria-labelledby="validation-summary-title">
<div class="forma-validation-summary__icon" aria-hidden="true">!</div>
<div>
<h2 class="forma-validation-summary__title" id="validation-summary-title">There are 2 responses to review</h2>
<ul class="forma-validation-summary__list">
<li><a href="#question-security">Question 4 requires a response.</a></li>
<li><a href="#question-allocation">Question 8 must total 10 points.</a></li>
</ul>
</div>
</div>
</forma-validation-summary>
Click or tap the code once to select all of it, then copy.
Examples
One off-screen error
A summary with a single item for a form where the problem may be below the fold. The heading uses the singular and the link targets the input's id.
Live demo. 1 native action works here and is verified by an outcome test.
There is 1 problem to fix
<forma-validation-summary class="forma-component-tag">
<div class="forma-stack">
<div class="forma-validation-summary" role="alert" tabindex="-1" aria-labelledby="validation-summary-single-error-title">
<div class="forma-validation-summary__icon" aria-hidden="true">!</div>
<div>
<h2 class="forma-validation-summary__title" id="validation-summary-single-error-title">There is 1 problem to fix</h2>
<ul class="forma-validation-summary__list">
<li><a href="#validation-summary-single-error-date">Enter the contract start date.</a></li>
</ul>
</div>
</div>
<div class="forma-field">
<label class="forma-field__label" for="validation-summary-single-error-date">Contract start date</label>
<input id="validation-summary-single-error-date" name="contract-start" type="date" required aria-invalid="true" aria-describedby="validation-summary-single-error-message">
<p class="forma-validation-message" id="validation-summary-single-error-message">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Enter the contract start date.
</p>
</div>
</div>
</forma-validation-summary>
Click or tap the code once to select all of it, then copy.
Summary above field-level messages
The full composition after a failed submit: the summary at the top of the form, and a matching Validation message at each field. Link text matches the field message so users recognize it when they arrive.
Static specimen. Submitting or resetting it needs the consuming application's form handling, which this documentation does not have. Its controls are shown for their markup and appearance and cannot be operated here.
<forma-validation-summary class="forma-component-tag">
<form class="forma-stack" action="#validation-summary-form-with-field-errors-title" novalidate>
<div class="forma-validation-summary" role="alert" tabindex="-1" aria-labelledby="validation-summary-form-with-field-errors-title">
<div class="forma-validation-summary__icon" aria-hidden="true">!</div>
<div>
<h2 class="forma-validation-summary__title" id="validation-summary-form-with-field-errors-title">There are 2 problems to fix</h2>
<ul class="forma-validation-summary__list">
<li><a href="#validation-summary-form-with-field-errors-name">Enter the vendor's legal name.</a></li>
<li><a href="#validation-summary-form-with-field-errors-tax">Enter a tax ID with 9 digits.</a></li>
</ul>
</div>
</div>
<div class="forma-field">
<label class="forma-field__label" for="validation-summary-form-with-field-errors-name">Legal name</label>
<input id="validation-summary-form-with-field-errors-name" name="legal-name" type="text" autocomplete="organization" required aria-invalid="true" aria-describedby="validation-summary-form-with-field-errors-name-error">
<p class="forma-validation-message" id="validation-summary-form-with-field-errors-name-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Enter the vendor's legal name.
</p>
</div>
<div class="forma-field">
<label class="forma-field__label" for="validation-summary-form-with-field-errors-tax">Tax ID</label>
<input id="validation-summary-form-with-field-errors-tax" name="tax-id" type="text" inputmode="numeric" value="12-34567" aria-invalid="true" aria-describedby="validation-summary-form-with-field-errors-tax-error">
<p class="forma-validation-message" id="validation-summary-form-with-field-errors-tax-error">
<span class="forma-validation-message__mark" aria-hidden="true">!</span>
Enter a tax ID with 9 digits.
</p>
</div>
<button type="submit">Save vendor</button>
</form>
</forma-validation-summary>
Click or tap the code once to select all of it, then copy.
Mobile
Each mobile example renders in its own document inside a real narrow viewport, so Forma's media and container queries run exactly as they would on a phone. Choose a width to compare.
Mobile survey page
A survey summary at phone width with longer link text. Items wrap inside the list while the mark stays in its own column.
Live demo. 3 native actions work here and are verified by an outcome test.
What changes at narrow widths
- The two-column grid keeps the mark in a narrow first column; the heading and list take the remaining width and wrap.
- Long link text wraps across lines, and each wrapped link remains one tappable target.
- No horizontal scrolling occurs at 320px; the list indent is only 1.25rem.
- When the application focuses the summary, the browser scrolls it into view at the top of the phone screen.
<forma-validation-summary class="forma-component-tag">
<div class="forma-validation-summary" role="alert" tabindex="-1" aria-labelledby="validation-summary-mobile-survey-page-title">
<div class="forma-validation-summary__icon" aria-hidden="true">!</div>
<div>
<h2 class="forma-validation-summary__title" id="validation-summary-mobile-survey-page-title">There are 3 responses to review</h2>
<ul class="forma-validation-summary__list">
<li><a href="#validation-summary-mobile-survey-page-title">Question 2: choose how often access reviews happen.</a></li>
<li><a href="#validation-summary-mobile-survey-page-title">Question 5: the allocation must total exactly 100 points.</a></li>
<li><a href="#validation-summary-mobile-survey-page-title">Question 9: describe the exception process in at least 20 characters.</a></li>
</ul>
</div>
</div>
</forma-validation-summary>
Click or tap the code once to select all of it, then copy.
Mobile · 320px
The canonical pattern in a true 320px viewport, the minimum width every Forma component must support without page-level horizontal scrolling.
Static specimen. Its links point to placeholder destinations that do not exist on this site. Its controls are shown for their markup and appearance and cannot be operated here.
API and configuration
Forma components have no JavaScript API. Their public contract is the markup: native elements and attributes you write, and the CSS hooks below. The CSS hook table is generated from the built stylesheet, so it always matches the shipped implementation.
| Attribute | On | Values | Default | Description |
|---|---|---|---|---|
role | div.forma-validation-summary | alert | — | Announces the summary when the application inserts it. A summary present at page load is not announced. |
tabindex | div.forma-validation-summary | -1 | — | Allows the application to move focus to the summary programmatically without adding it to the Tab order. |
aria-labelledby | div.forma-validation-summary | id of .forma-validation-summary__title | — | Names the summary by its heading, so focusing it announces the count. |
href | a | #id of the affected control or group | — | Takes the user to the problem. Point at the input's id, or the fieldset's id for a group. |
aria-hidden | .forma-validation-summary__icon | true | — | Hides the decorative mark. |
| Hook | Kind | Values or default | Description |
|---|---|---|---|
.forma-validation-summary | Block class | — | Root grid with a mark column and a content column, a 2px accent border and a secondary surface. |
.forma-validation-summary__icon | Element class | — | Bordered circular mark shared in style with the validation message mark. Decorative. |
.forma-validation-summary__list | Element class | — | Bulleted list of links, one per problem. |
.forma-validation-summary__title | Element class | — | Heading that states the number of problems; sans-serif at 1rem regardless of heading level. |
| Keys | Result |
|---|---|
| Tab / Shift+Tab | Moves through the links. The summary container is reachable only by programmatic focus. |
| Enter | Follows the focused link to the affected control (native link behavior). |
| Event | Description |
|---|---|
submit / invalid | Native form events the application may use to build and insert the summary. Forma defines no events. |
Form behavior
The summary is not a form control. Use novalidate on the form when the application renders its own summary instead of the browser's validation bubbles.
States
| State | How it is expressed | Presentation |
|---|---|---|
| Inserted after submit | role="alert" element added to the DOM | Announced by assistive technology and typically focused by the application. |
| Focused | :focus-visible via tabindex="-1" and programmatic focus | Shows the shared focus ring around the whole summary. |
| Updated | application rewrites the heading count and list | The application removes fixed items or the whole summary once everything is resolved. |
Accessibility
Forma provides
- Uses a heading, a count in words, a mark and a heavy border, so the summary is recognizable without color.
- Maps the border to
CanvasTextin forced colors. - Renders every item as a native link with the standard focus indicator.
Your application supplies
- Insert the summary after a failed submit and move focus to it.
- Keep link text identical or close to the field-level Validation message so users recognize the target.
- Point each link at an element that exists and is visible; for grouped controls target the fieldset.
- Update or remove the summary as problems are fixed, and never include raw exception text.
Responsive behavior
- Two-column grid (
auto minmax(0, 1fr)): the mark column is intrinsic and the content column absorbs the remaining width. - Headings and link text wrap; there are no breakpoints.
- The summary fills its container; place it at the top of the form so it is the first thing seen after focus moves.
Motion
- No animation: the summary appears with the application's DOM insertion, and focus movement scrolls it into view natively.
Usage guidance
Do
- State the count in the heading ("There are 2 problems to fix").
- List problems in the order the fields appear in the form.
Avoid
- Showing the summary before the user has tried to submit.
- Generic items such as "Invalid input" that do not name the field.
Verification specimens
Generated fault-injection specimens expose content, spacing, color-cue, and reduced-effective-contrast risks. They screen presentation robustness as engineering screens without claiming human-subject validation.