Show errors

When a form is submitted with mistakes, reload the page with the errors in three places.

An error summary at the top of the main content, listing every error as a link to its field.
An error message on each field, with the field marked by ag-field--error.
The page title prefixed with "Error:" so it is announced before anything else.

With afrigov.js loaded, focus moves to the summary on load. Without it, the summary is still the first thing after the heading.

The pattern

There is a problem

Enter an email address in the correct format, like name@example.com
Enter your National ID number

Email address Enter an email address in the correct format, like name@example.com

National ID number Enter your National ID number

Show HTML

<div class="ag-error-summary" role="alert" tabindex="-1" data-ag-no-autofocus aria-labelledby="es-title">
  <h2 class="ag-error-summary__title" id="es-title">There is a problem</h2>
  <ul class="ag-error-summary__list">
    <li><a href="#err-email">Enter an email address in the correct format, like name@example.com</a></li>
    <li>
      <a href="#err-nin">Enter your <span data-docs-string="id-name">National ID number</span></a>
    </li>
  </ul>
</div>

<div class="ag-field ag-field--error">
  <label class="ag-label" for="err-email">Email address</label>
  <span class="ag-error-message" id="err-email-error">
    <span class="ag-visually-hidden">Error:</span> Enter an email address in the correct format, like name@example.com
  </span>
  <input
    class="ag-input"
    id="err-email"
    name="email"
    type="email"
    aria-invalid="true"
    aria-describedby="err-email-error"
    value="amina@"
  />
</div>

<div class="ag-field ag-field--error ag-mb-0">
  <label class="ag-label" for="err-nin" data-docs-string="id-name">National ID number</label>
  <span class="ag-error-message" id="err-nin-error">
    <span class="ag-visually-hidden">Error:</span> Enter your
    <span data-docs-string="id-name">National ID number</span>
  </span>
  <input
    class="ag-input ag-input--width-20"
    id="err-nin"
    name="nin"
    type="text"
    inputmode="numeric"
    aria-invalid="true"
    aria-describedby="err-nin-error"
  />
</div>

Writing error messages

Say what to do, not what went wrong: "Enter your date of birth", not "Invalid date".
Use the same words in the summary and at the field.
One error per field. If several things are wrong, say the first.
Do not blame the person. No "You failed to…".
Start each message with a visually hidden "Error:" so screen readers announce it as one.

Do not

Validate on every keystroke. People make mistakes while typing that they would fix themselves.
Clear the form. Keep what was entered so only the wrong field needs attention.
Rely on a red border. Colour-blind readers will not see it; the text and the summary are the signal.