Skip to main content

Testing

Help us to improve the ONS Design System. Take part in a short study

Help users to Correct errors

Check that a user enters something into a mandatory field and then check that what they enter is valid. If information is missing or incorrect, advise the user on how to fix it.

When to use this pattern

Use this pattern when you need to help your users enter correct and required information in a form. Validation should occur after the user submits the form.

When not to use this pattern

Do not use this pattern to tell the user if there is a problem with the service, or if they do not have permission to do something. For this situation, use the error or status pages pattern.

How to use this pattern

If the user tries to submit the form when there is missing or incorrect information, you must:

  • show the page again, keeping the user’s information in the form fields as they entered it
  • add “Error: ” before the page <title> for screen readers to read out first
  • show an error summary at the top of the page that lists all the errors, and move keyboard focus to it
  • show the error details next to each field that has missing or incorrect information

Error summary

An error panel with title component lists all the errors on the page. It must be displayed at the top of the page’s <main> container and above the <h1> heading when the page reloads. This ensures it is the first element on the page to be read.

<div aria-labelledby="error-summary-title" role="alert" tabindex="-1" autofocus="autofocus" class="panel panel--error">
  <div class="panel__header">
    <h2 id="error-summary-title" data-qa="error-header" class="panel__title u-fs-r--b">There are 2 problems with your answer</h2>
  </div>
  <div class="panel__body">
    <ol class="list">
      <li class="list__item ">
        <a href="#container-test-number" class="list__link js-inpagelink">Enter a number</a>
      </li>
      <li class="list__item ">
        <a href="#container-test-percent" class="list__link js-inpagelink">Enter a number less than or equal to 100</a>
      </li>
    </ol>
  </div>
</div>
{% from "components/panel/_macro.njk" import onsPanel %}
{% from "components/lists/_macro.njk" import onsList %}
{% call
    onsPanel({
        title: "There are 2 problems with your answer",
        type: "error",
        "dsExample": isPatternLib
    })
%}
{{
    onsList({
        "element": "ol",
        "itemsList": [
            {
                "text": "Enter a number",
                "url": "#container-test-number",
                "classes": "js-inpagelink"
            },
            {
                "text": "Enter a number less than or equal to 100",
                "url": "#container-test-percent",
                "classes": "js-inpagelink"
            }
        ]
    })
}}
{% endcall %}

The panel contains assistive technology attributes. As soon as the page is loaded, the keyboard focus is on the panel and the user is told about this new information.

Error summary panel title

The panel’s title lets the user know there is an error with their answer. Use the following content:

  • “There is a problem with your answer” if the page is a question
  • “There is a problem with this page” if the page is not a question

If there is more than one error on the page, the title must display the number of errors, for example, “There are 2 problems with your answer”.

Error summary panel body

The panel’s body must contain an ordered list of links for each error. Set element to “ol” if using the onsList macro. Each list item must:

  • describe the specific error and help the user fix it
  • link to the field or fieldset that contains the validation error on the page
  • contain a url key value that matches the id of the panel wrapping the field or fieldset with the error – this needs to start with a hash, for example, #email-input, so Javascript can focus the corresponding input

Guidance on specific error messages can be found on the page for each form component.

Error details

You must use an error details panel to wrap each field that has missing or incorrect information. This needs to describe the error and help the user fix it.

<div class="panel panel--error panel--no-title u-mb-s" id="number-of-employees-error">
  <span class="u-vh">Error: </span>
  <div class="panel__body">
    <p class="panel__error">
      <strong>Enter a number</strong>
    </p>
    <div class="field">
      <label class="label  " for="number-of-employees">Number of employees paid monthly
      </label>
      <input type="text" id="number-of-employees" class="input input--text input-type__input input--error input--w-5" pattern="[0-9]*" inputmode="numeric" min required="required" />
    </div>
  </div>
</div>
<div class="panel panel--error panel--no-title u-mb-s">
  <span class="u-vh">Error: </span>
  <div class="panel__body">
    <p class="panel__error">
      <strong>Enter a number less than or equal to 100</strong>
    </p>
    <div class="field">
      <label class="label  " for="suffixed">Percentage of employees paid monthly
      </label>
      <span class="input-type">
        <span class="input-type__inner">
          <input type="text" id="suffixed" class="input input--text input-type__input input--error input--w-3" title="per cent" value="101" pattern="[0-9]*" inputmode="numeric" required="required" />
          <abbr class="input-type__type js-input-abbr" aria-hidden="true" title="per cent">%</abbr>
        </span>
      </span>
    </div>
  </div>
</div>
{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "number-of-employees",
        "type": "number",
        "classes": "input--w-5",
        "required": true,
        "attributes": {
            "min": 0
        },
        "label": {
            "text": "Number of employees paid monthly"
        },
        "error": {
            "id": "number-of-employees-error",
            "text": "Enter a number",
            "dsExample": isPatternLib
        }
    })
}}
{{
    onsInput({
        "id": "suffixed",
        "type": "number",
        "classes": "input--w-3",
        "value": "101",
        "required": true,
        "label": {
            "text": "Percentage of employees paid monthly"
        },
        "suffix": {
            "title": "per cent",
            "text": "%"
        },
        "error": {
            "text": "Enter a number less than or equal to 100",
            "dsExample": isPatternLib
        }
    })
}}

The error component is called within each component by providing a text and id value within the error object.

The text string for the error details panel must be the same as its corresponding link in the error summary panel.

Guidance on specific error messages can be found on the page for each form component.

Example

The prototype provides an example of form validation for inputs that have missing or incorrect information. Attempt to submit the form as it is to see the error validation in action.

Important information:
Note: The form in the example prototype will always fail validation.

Help improve this pattern

Let us know how we could improve this pattern or share your user research findings.

Discuss the ‘Correct errors’ pattern on GitHub