Form elements - Error message

Use an error message when there is a validation error. Explain what went wrong and how to fix it.

Open this in context error message example in new window
Copy in context error message code 
<div class="hse-form-group hse-form-group--error">
  <fieldset class="hse-fieldset" aria-describedby="dob-day-error-hint dob-day-error-error" role="group">
    <legend class="hse-fieldset__legend hse-fieldset__legend--l">
      <h1 class="hse-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <span class="hse-hint" id="dob-day-error-hint">
      For example, 31 3 1980
    </span>

    <span class="hse-error-message" id="dob-day-error-error">
      <span class="hse-u-visually-hidden">Error:</span> Date of birth must be in the past
    </span>

    <div class="hse-date-input" id="dob-day-error">
      <div class="hse-date-input__item">
        <div class="hse-form-group">
          <label class="hse-label hse-date-input__label" for="dob-day-error-day">
            Day
          </label>
          <input class="hse-input hse-date-input__input hse-input--width-2 hse-input--error" id="dob-day-error-day" name="dob-day-error-day" type="number" value="15" pattern="[0-9]*">
        </div>
      </div>
      <div class="hse-date-input__item">
        <div class="hse-form-group">
          <label class="hse-label hse-date-input__label" for="dob-day-error-month">
            Month
          </label>
          <input class="hse-input hse-date-input__input hse-input--width-2 hse-input--error" id="dob-day-error-month" name="dob-day-error-month" type="number" value="3" pattern="[0-9]*">
        </div>
      </div>
      <div class="hse-date-input__item">
        <div class="hse-form-group">
          <label class="hse-label hse-date-input__label" for="dob-day-error-year">
            Year
          </label>
          <input class="hse-input hse-date-input__input hse-input--width-4 hse-input--error" id="dob-day-error-year" name="dob-day-error-year" type="number" value="2084" pattern="[0-9]*">
        </div>
      </div>
    </div>
  </fieldset>

</div>
Close in context error message code
Nunjucks macro options

Use options to customise the appearance, content and behaviour of a component when using a macro, for example, changing the text.

Some options are required for the macro to work; these are marked as "Required" in the option description.

If you're using Nunjucks macros in production with "html" options, or ones ending with "html", you must sanitise the HTML to protect against cross-site scripting exploits.

Nunjucks arguments for in context error message
Name Type Required Description
Name text Type string Required true Description If `html` is set, this is not required. Text to use within the error message. If `html` is provided, the `text` argument will be ignored.
Name html Type string Required true Description If `text` is set, this is not required. HTML to use within the error message. If `html` is provided, the `text` argument will be ignored.
Name id Type string Required false Description Id attribute to add to the error message span tag.
Name classes Type string Required false Description Classes to add to the error message span tag.
Name attributes Type object Required false Description HTML attributes (for example data attributes) to add to the error message span tag.
Copy in context error message code 
{% from 'error-message/macro.njk' import errorMessage %}
{% from 'date-input/macro.njk' import dateInput %}

{{ dateInput({
  "id": "dob-day-error",
  "namePrefix": "dob-day-error",
  "fieldset": {
      "legend": {
      "text": "What is your date of birth?",
      "classes": "hse-fieldset__legend--l",
      "isPageHeading": true
      }
  },
  "hint": {
      "text": "For example, 31 3 1980"
  },
  "errorMessage": {
      "text": "Date of birth must be in the past"
  },
  "items": [
      {
      "name": "day",
      "classes": "hse-input--width-2 hse-input--error",
      value: 15
      },
      {
      "name": "month",
      "classes": "hse-input--width-2 hse-input--error",
      value: 3
      },
      {
      "name": "year",
      "classes": "hse-input--width-4 hse-input--error",
      value: 2084
      }
  ]
  }) }}
Close in context error message code

When to use an error message

Use the error message component when there is an error with validating information. For example when:

  • you need to tell the user to choose an option before continuing
  • you need the user to correct or change their input to match what your system can accept

Follow the NHS guidance on how to write good questions for forms and make them easy to use so that users never see an error message.

How to write good questions for forms - service-manual.nhs.uk

When not to use an error message

Only display an error when someone tries to move to the next part of the service. Do not show error messages:

  • when users select or tab to a field
  • as they are typing
  • when they move away from a field

Do not use error messages to tell users:

  • that they are not eligible to do something
  • do not have permission to do something

Instead, take them to a screen that:

  • explains why you cannot accept the entry or selection
  • tells them what to do next
  • includes a way to leave the transaction

How to use an error message

For each error:

  • put the message in an error summary at the top of the page the user is on
  • put the message in red after the question text and hint text
  • use a red border to visually connect the message and the question it belongs to
  • if the error relates to specific text fields in the question, give these a red border

To help screen reader users, the error message component includes a hidden "Error:" before the error message. For example, these users will hear; "Error: Date of birth must be in the past".

Using an error summary

Summarise all errors at the top of the page the user is on using error summary.

Updated: September 2023