Cookies on ons.gov.uk

Cookies are small files stored on your device when you visit a website. We use some essential cookies to make this website work.

We would like to set additional cookies to remember your settings and understand how you use the site. This helps us to improve our services.

View cookies

You have accepted all additional cookies. You have rejected all additional cookies. You can change your cookie preferences at any time.

Skip to main content

Help users to Correct errors

Overview

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 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.

Open this example in a new tab (Example Error Summary)

Example Error Summary contents

Nunjucks

{% from "components/panel/_macro.njk" import onsPanel %}
{% from "components/list/_macro.njk" import onsList %}

{% call
    onsPanel({
        title: "There are 2 problems with your answer",
        type: "error"
    })
%}
{{
    onsList({
        "element": "ol",
        "itemsList": [
            {
                "text": "Enter the number of employees paid monthly",
                "url": "#container-test-number",
                "variants": "inPageLink"
            },
            {
                "text": "Enter a number that is less than 101",
                "url": "#container-test-percent",
                "variants": "inPageLink"
            }
        ]
    })
}}
{% endcall %}

HTML

<div aria-labelledby="alert" role="alert" tabindex="-1" class="ons-panel ons-panel--error">
  <div class="ons-panel__header">
    <h2 id="alert" data-qa="error-header" class="ons-panel__title ons-u-fs-r--b">There are 2 problems with your answer
    </h2>
  </div>
  <div class="ons-panel__body">
    <ol class="ons-list">
      <li class="ons-list__item">
        <a href="#container-test-number" class="ons-list__link ons-js-inpagelink">Enter the number of employees paid
          monthly</a>
      </li>
      <li class="ons-list__item">
        <a href="#container-test-percent" class="ons-list__link ons-js-inpagelink">Enter a number that is less than
          101</a>
      </li>
    </ol>
  </div>
</div>

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 on the page. 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 a list of links for each error. Using the onsList macro, set "element": "ol". If there is only one error, the macro will wrap the link in a <p> instead of the ordered list markup. Each error link 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 component or pattern.

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.

Open this example in a new tab (Example Error Details)

Example Error Details contents

Nunjucks

{% from "components/input/_macro.njk" import onsInput %}
{{
    onsInput({
        "id": "number-of-employees",
        "type": "number",
        "width": "5",
        "attributes": {
            "min": 0
        },
        "label": {
            "text": "Number of employees paid monthly"
        },
        "error": {
            "id": "number-of-employees-error",
            "text": "Enter the number of employees paid monthly"
        }
    })
}}

{{
    onsInput({
        "id": "percentage-of-employees",
        "type": "number",
        "width": "3",
        "value": "110",
        "label": {
            "text": "Percentage of employees paid monthly"
        },
        "suffix": {
            "title": "per cent",
            "text": "%",
            "id": "employees-percentage-suffix"
        },
        "error": {
            "text": "Enter a number that is less than 101"
        }
    })
}}

HTML

<div class="ons-panel ons-panel--error ons-panel--no-title" id="number-of-employees-error">
  <span class="ons-panel__assistive-text ons-u-vh">Error: </span>
  <div class="ons-panel__body">
    <p class="ons-panel__error">
      <strong>Enter the number of employees paid monthly</strong>
    </p>
    <div class="ons-field">
      <label class="ons-label" for="number-of-employees">Number of employees paid monthly</label>
      <input type="text" id="number-of-employees"
        class="ons-input ons-input--text ons-input-type__input ons-input--error ons-input-number--w-5" pattern="[0-9]*"
        inputmode="numeric" min />
    </div>
  </div>
</div>
<div class="ons-panel ons-panel--error ons-panel--no-title">
  <span class="ons-panel__assistive-text ons-u-vh">Error: </span>
  <div class="ons-panel__body">
    <p class="ons-panel__error">
      <strong>Enter a number that is less than 101</strong>
    </p>
    <div class="ons-field">
      <label class="ons-label" for="percentage-of-employees">Percentage of employees paid monthly</label>
      <span class="ons-input-type">
        <span class="ons-input-type__inner">
          <input type="text" id="percentage-of-employees"
            class="ons-input ons-input--text ons-input-type__input ons-input--error ons-input-number--w-3"
            aria-labelledby="percentage-of-employees employees-percentage-suffix" value="110" pattern="[0-9]*"
            inputmode="numeric" />
          <abbr id="employees-percentage-suffix" class="ons-input-type__type ons-js-input-abbr" aria-label="per cent"
            role="figure" title="per cent">%</abbr>
        </span>
      </span>
    </div>
  </div>
</div>

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.

View example prototype (opens in a new tab) 

Help improve this page

Let us know how we could improve this page, or share your user research findings. Discuss the ‘Correct errors’ pattern on GitHub (opens in a new tab)