Skip to main content

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" class="ons-panel ons-panel--error">
  <div class="ons-panel__header">
    <h2 id="error-summary-title" 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  ">Enter a number</a>
      </li>
      <li class="ons-list__item">
        <a href="#container-test-percent" class="ons-list__link  ">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",
                "variants": "inPageLink"
            },
            {
                "text": "Enter a number less than or equal to 100",
                "url": "#container-test-percent",
                "variants": "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 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.

<div class="ons-panel ons-panel--error ons-panel--no-title ons-u-mb-s" id="number-of-employees-error">
  <span class="ons-u-vh">Error: </span>
  <div class="ons-panel__body">
    <p class="ons-panel__error">
      <strong>Enter a number</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 required="required" />
    </div>
  </div>
</div>
<div class="ons-panel ons-panel--error ons-panel--no-title ons-u-mb-s">
  <span class="ons-u-vh">Error: </span>
  <div class="ons-panel__body">
    <p class="ons-panel__error">
      <strong>Enter a number less than or equal to 100</strong>
    </p>
    <div class="ons-field">
      <label class="ons-label  " for="suffixed">Percentage of employees paid monthly
      </label>
      <span class="ons-input-type">
        <span class="ons-input-type__inner">
          <input type="text" id="suffixed" class="ons-input ons-input--text ons-input-type__input ons-input--error ons-input-number--w-3" title="per cent" value="101" pattern="[0-9]*" inputmode="numeric" required="required" />
          <abbr class="ons-input-type__type ons-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",
        "width": "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",
        "width": "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