Components Error message

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

<div class="govuk-form-group govuk-form-group--error">
  <fieldset class="govuk-fieldset" aria-describedby="dob-hint dob-error" role="group">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--xl">
      <h1 class="govuk-fieldset__heading">
        What is your date of birth?
      </h1>
    </legend>
    <span id="dob-hint" class="govuk-hint">
    For example, 31 3 1980
  </span>
    <span id="dob-error" class="govuk-error-message">
    Date of birth must be in the past
  </span>
    <div class="govuk-date-input" id="dob">

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-day">
          Day
        </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2 undefined" id="dob-day" name="dob-day" type="number" value="6" pattern="[0-9]*">
        </div>
      </div>

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-month">
          Month
        </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-2 undefined" id="dob-month" name="dob-month" type="number" value="3" pattern="[0-9]*">
        </div>
      </div>

      <div class="govuk-date-input__item">
        <div class="govuk-form-group">
          <label class="govuk-label govuk-date-input__label" for="dob-year">
          Year
        </label>
          <input class="govuk-input govuk-date-input__input govuk-input--width-4 undefined" id="dob-year" name="dob-year" type="number" value="2076" pattern="[0-9]*">
        </div>
      </div>
    </div>
  </fieldset>
</div>
{% from "date-input/macro.njk" import govukDateInput %}

{{ govukDateInput({
  fieldset: {
    legend: {
      text: "What is your date of birth?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--xl"
    }
  },
  hint: {
    text: "For example, 31 3 1980"
  },
  errorMessage: {
    text: "Date of birth must be in the past"
  },
  id: "dob",
  name: "dob",
  items: [
    {
      name: "day",
      value: "6"
    },
    {
      name: "month",
      value: "3"
    },
    {
      name: "year",
      value: "2076"
    }
  ]
}) }}

You can configure this component using the Nunjucks macro arguments.

When to use this component

Show an error message next to the field and in the error summary when there is a validation error.

Use standard messages for different components.

Try to design your service to be easy to use and understand so someone never sees an error message.

When not to use this component

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 or do not have permission to do something. Instead, take them to a screen that:

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

How it works

For each error:

  • 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 within the question, give these a red border as well

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

There are 2 ways to use the error message component. You can use HTML or, if you are using Nunjucks or the GOV.UK Prototype Kit, you can use the Nunjucks macro.

Legend

<div class="govuk-form-group govuk-form-group--error">
  <fieldset class="govuk-fieldset" aria-describedby="nationality-hint nationality-error">
    <legend class="govuk-fieldset__legend govuk-fieldset__legend--xl">
      <h1 class="govuk-fieldset__heading">
        What is your nationality?
      </h1>
    </legend>
    <span id="nationality-hint" class="govuk-hint">
    If you have dual nationality, select all options that are relevant to you.
  </span>
    <span id="nationality-error" class="govuk-error-message">
    Select if you are British, Irish or a citizen of a different country
  </span>
    <div class="govuk-checkboxes">
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="nationality-1" name="nationality" type="checkbox" value="british">
        <label class="govuk-label govuk-checkboxes__label" for="nationality-1">
        British
      </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="nationality-2" name="nationality" type="checkbox" value="irish">
        <label class="govuk-label govuk-checkboxes__label" for="nationality-2">
        Irish
      </label>
      </div>
      <div class="govuk-checkboxes__item">
        <input class="govuk-checkboxes__input" id="nationality-3" name="nationality" type="checkbox" value="other">
        <label class="govuk-label govuk-checkboxes__label" for="nationality-3">
        Citizen of another country
      </label>
      </div>
    </div>
  </fieldset>
</div>
{% from "checkboxes/macro.njk" import govukCheckboxes %}

{{ govukCheckboxes({
  idPrefix: "nationality",
  name: "nationality",
  fieldset: {
    legend: {
      text: "What is your nationality?",
      isPageHeading: true,
      classes: "govuk-fieldset__legend--xl"
    }
  },
  hint: {
    text: "If you have dual nationality, select all options that are relevant to you."
  },
  errorMessage: {
    text: "Select if you are British, Irish or a citizen of a different country"
  },
  items: [
    {
      value: "british",
      text: "British"
    },
    {
      value: "irish",
      text: "Irish"
    },
    {
      value: "other",
      text: "Citizen of another country"
    }
  ]
}) }}

You can configure this component using the Nunjucks macro arguments.

Label

<div class="govuk-form-group govuk-form-group--error">
  <label class="govuk-label" for="national-insurance-number">
    National Insurance number
  </label>
  <span id="national-insurance-number-hint" class="govuk-hint">
    It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’.
  </span>
  <span id="national-insurance-number-error" class="govuk-error-message">
    Enter a National Insurance number in the right format
  </span>
  <input class="govuk-input govuk-input--error" id="national-insurance-number" name="national-insurance-number" type="text" aria-describedby="national-insurance-number-hint national-insurance-number-error">
</div>
{% from "input/macro.njk" import govukInput %}

{{ govukInput({
  label: {
    text: "National Insurance number"
  },
  hint: {
    text: "It’s on your National Insurance card, benefit letter, payslip or P60. For example, ‘QQ 12 34 56 C’."
  },
  id: "national-insurance-number",
  name: "national-insurance-number",
  errorMessage: {
    text: "Enter a National Insurance number in the right format"
  }
}) }}

You can configure this component using the Nunjucks macro arguments.

Be clear and concise

Describe what has happened and tell them how to fix it. The message must be in plain English, use positive language and get to the point.

Do not use:

  • technical jargon like ‘form post error’, ‘unspecified error’ and ‘error 0x0000000643’
  • words like ‘forbidden’, ‘illegal’, ‘you forgot’ and ‘prohibited’
  • ‘please’ because it implies a choice
  • ‘sorry’ because it does not help fix the problem
  • ‘valid’ and ‘invalid’ because they do not add anything to the message
  • humourous, informal language like ‘oops’

Above all, aim for clarity.

Read the message out loud to see if it sounds like something you would say.

Be consistent

Use the same message next to the field and in the error summary so they:

  • look, sound and mean the same
  • make sense out of context
  • reduce the cognitive effort needed to understand what has happened

Use the question or form label in the error to provide context. For example, ‘Enter how many hours you work a week’ for ‘How many hours do you work a week?’

Be specific

General errors are not helpful to everyone. They do not make sense out of context. Avoid messages like:

  • ‘An error occurred’
  • ‘Answer the question’
  • ‘Select an option’
  • ‘Fill in the field’
  • ‘This field is required’

Different errors need different messages. For example, text fields may be:

  • empty
  • too long
  • too short
  • using characters that are not allowed
  • in the wrong format

An error for a specific situation is more helpful. It will tell someone what has happened and how to fix it.

Use instructions and descriptions

Some errors work better as instructions and some work better as descriptions. For example:

  • ‘Enter your first name’ is clearer, more direct and natural than ‘First name must have an entry’
  • ‘Enter a first name that is 35 characters or less’ is wordier, less direct and natural than ‘First name must be 35 characters or less’
  • ‘Enter a date after 31 August 2017 for when you started the course’ is wordier, less direct and natural than ‘Date you started the course must be after 31 August 2017’

Use both instructions and descriptions, but use them consistently. For example, use an instruction for empty fields like ‘Enter your name’, but a description like ‘Name must be 35 characters or less’ for entries that are too long.

Track errors

Find out how often people see them. This will let you:

  • improve content
  • A/B test variations
  • redesign a journey

Research on this component

Error messages designed using this guidance have been tested with all types of users in live services, including tax credits.

Research showed users:

  • understood what went wrong
  • knew how to fix the problem
  • were able to recover from the error

If you’ve used this component, get in touch to share your user research findings.

Get in touch

If you’ve got a question, idea or suggestion share it in #govuk-design-system on cross-government Slack (open in app) or email the Design System team on govuk-design-system-support@digital.cabinet-office.gov.uk

Discuss ‘Error message’ on GitHub