Feedback & status

AppErrorSummary

The list of a form's errors after a failed submit, each one a link that jumps to its field.

<app-error-summary><app-error-summary-item field="name">Enter the company name.</app-error-summary-item></app-error-summary>

<app-error-summary> lists every error on a form after a failed submit. Put it at the top of the form, above the first field. It takes focus when the page loads, so a screen reader and a keyboard user start from the list instead of from the Save button.

Each message is a link. Clicking it moves focus to that field, found by its id or name. Keep each field's own error as well. The summary tells the reader what is wrong in one place, and the field message shows where. It renders nothing when it has no items.

Try it

A small real form. Press Save with the fields empty, or with a bad email. The page reloads with the summary on top, and it takes focus. Click a message to jump to its field.

A form with two required fields
The server validates the submit and re-renders the values. Every field also shows its own message.
Show code 
<form method="get" action="/Components/AppErrorSummary#demo" novalidate>
    <input type="hidden" name="demo" value="1" />
    <app-error-summary>
        <app-error-summary-item field="demoName">Enter the company name.</app-error-summary-item>
        <app-error-summary-item field="demoEmail">Enter an email address like name@company.in</app-error-summary-item>
    </app-error-summary>
    <app-input label="Company name" name="demoName" required="true" error="Enter the company name." />
    <app-input label="Email" name="demoEmail" type="email" required="true" error="Enter an email address like name@company.in" />
    <app-button type="submit">Save</app-button>
</form>
Render it only after a failed submitWrap the summary in a check for errors, or give it no items. With no items it renders nothing. On a real page the summary only exists after a submit, so taking focus on load is what you want.

Playground

The title and the number of errors, live. Each change re-renders the real tag helper on the server. Auto focus is switched off here so this page does not jump. The markup underneath is the exact call that produced the summary above it.

<app-error-summary auto-focus="false">
    <app-error-summary-item field="name">Enter the company name.</app-error-summary-item>
    <app-error-summary-item field="email">Enter an email address like name@company.in</app-error-summary-item>
</app-error-summary>

Basic

One <app-error-summary-item> per error. Its field is the id or name of the input to focus, and its text is the message. The heading counts the items for you.

Two errors, default title
The heading reads Fix 2 fields to continue. With one error it reads Fix 1 field to continue.
Show code 
<app-error-summary auto-focus="false">
    <app-error-summary-item field="name">Enter the company name.</app-error-summary-item>
    <app-error-summary-item field="email">Enter an email address like name@company.in</app-error-summary-item>
</app-error-summary>
auto-focus is off on this page onlyEvery static example here sets auto-focus="false" so the page does not jump to the first one when it loads. On a real form, leave it on. Turn it off only where the summary is shown for reference, such as documentation.

Custom title

Set title to replace the default heading. Use it when the form has its own wording, such as a save or a send.

A title that names the action
The list below it is unchanged.
Show code 
<app-error-summary title="Fix 2 fields to save" auto-focus="false">
    <app-error-summary-item field="name">…</app-error-summary-item>
    <app-error-summary-item field="email">…</app-error-summary-item>
</app-error-summary>

When to use

Use it when

  • A form with more than one field failed to submit, and the reader needs to see everything wrong at once.
  • Keyboard and screen reader users should land on the list and reach each field from it.
  • You also show each field's own error, so the list and the fields agree.

Reach for something else when

  • You have one message that does not belong to a field. → app-alert
  • The feedback is brief, such as Saved or Copied. → WUI.toast
  • The form has a single field. → that field's own error attribute

Every option

The whole surface of the tag helper. Each cell has auto focus off, so nothing here takes focus.

Default title: one error vs. three

1 error, default title
3 errors, default title

title

title="Check these fields before you send"

Attributes

AttributeTypeDefaultDescription
titlestringFix N fields to continueThe heading. Defaults to Fix N fields to continue, or Fix 1 field to continue for one item.
idstringgeneratedThe id of the summary. The heading takes {id}-title.
auto-focusbooltrueTake focus when the page loads. React's autoFocus. Turn it off only where the summary is shown for reference, such as documentation.
classstring-Extra classes merged onto the alert. React's className.
app-error-summary-item fieldstring-On an <app-error-summary-item> child: the id or name of the input to focus. A custom field focuses its inner control.
app-error-summary-item contentstring-The element's text is the message and the link text. An empty item is left out. With no items the summary renders nothing.