Error summary

On this page

Preview

Error summary with multiple errors

import { ErrorSummary } from '@govtech-bb/react';

<ErrorSummary
  errors={[
    {
      href: '#email',
      label:
        'Enter an email address in the correct format, like name@example.com',
    },
    { href: '#parish', label: 'Select a parish' },
    { href: '#terms', label: 'Accept the terms and conditions' },
  ]}
/>;

<div
  class="govbb-error-summary"
  role="alert"
  aria-labelledby="error-summary-title"
>
  <h2 id="error-summary-title" class="govbb-error-summary__title">
    There is a problem
  </h2>
  <ul class="govbb-error-summary__list">
    <li>
      <a class="govbb-link govbb-error-summary__link" href="#email"
        >Enter an email address in the correct format, like name@example.com</a
      >
    </li>
    <li>
      <a class="govbb-link govbb-error-summary__link" href="#parish"
        >Select a parish</a
      >
    </li>
    <li>
      <a class="govbb-link govbb-error-summary__link" href="#terms"
        >Accept the terms and conditions</a
      >
    </li>
  </ul>
</div>

The Error Summary component lists every problem on a page after a failed form submission, with a link to each field that needs to be fixed. It gives users a single place to see what went wrong instead of hunting through the form for individual error messages.

Usage

When to use

Use an error summary whenever a submitted form contains a validation error, even if there is only one.
Use it together with an error message beside every field that needs correction.

When not to use

Do not use an error summary for service notices, warnings or successful outcomes.
Do not show it before the user submits the form or has had a reasonable chance to answer.

Best practices

Help users reach each error

Place the summary at the start of the form, move focus to it after an unsuccessful submission and link every message to the relevant field or group.

Keep messages consistent

Use the heading “There is a problem”. Match each summary message to the inline message and prefix the document title with “Error:” so the state is announced as soon as the page loads.

Placement and focus

Render the error summary at the top of the page, immediately after a failed submission, and move keyboard focus to it so users land on the summary straight away rather than having to scroll to find it. This matters most for keyboard and screen reader users, who otherwise have no way of knowing the submission failed.

Linking errors to fields

Each item in the list should link to the field that caused the error, using the input’s id as the anchor. Use the same wording in the summary link and the field-level error message, so users are not left guessing whether they refer to the same problem.

Single error

Show the summary even when only one field has failed. Keeping the behaviour the same on every failed submission means keyboard focus always lands in the same place and users learn one pattern, not two. The field itself still gets its own error message.

Error summary with a single error

Open in new tab

import { useRef } from 'react';
import { ErrorSummary } from '@govtech-bb/react';

// after a failed submit: summaryRef.current?.focus()
const summaryRef = useRef<HTMLDivElement>(null);

<ErrorSummary
  ref={summaryRef}
  errors={[{ href: '#full-name', label: 'Enter your full name' }]}
/>;

<div
  class="govbb-error-summary"
  role="alert"
  aria-labelledby="error-summary-title"
>
  <h2 id="error-summary-title" class="govbb-error-summary__title">
    There is a problem
  </h2>
  <ul class="govbb-error-summary__list">
    <li>
      <a class="govbb-link govbb-error-summary__link" href="#full-name"
        >Enter your full name</a
      >
    </li>
  </ul>
</div>