Skip to main content

Error messages

Supported products
  • Central CMS
  • Central Forms
  • Central Connect

Error messages are a critical user interface component, they must explain to people that something unexpected has occurred and how to resolve it.

General guidance​

The choice of language used in an error message should be seen as a design task as important as anything else, the choice of wording is crucial if the user has any chance of resolving an error condition.

Error messages should:

  • Be visually distinct, obvious and easy to spot
  • Be placed close to the source of the problem
  • Use plain language
  • Be brief

Error messages should not:

  • be vague, such as saying ‘a problem occurred’
  • Use technical language, like ‘transcoding failed’
  • say ‘sorry’, because it does not help fix the problem
  • attempt to use humour, like saying 'oops, something went wrong’

General errors​

Page title​

The <title> attribute of the page should be prepended with the word Error, as well as acting as a visual indicator that the tab contains an error, it is also the first word that a screen reader will announce when the page has loaded, informing screen reader users that something has gone wrong.

The title attribute can be set on page load in the title block, you'll need to add the related logic to update this based on a form validation failure.

{% block title %}
    Error - Jadu Control Center - Create Document
{% endblock %}

Flash message​

Flash messages are displayed at the top of the user interface and will often be the first indication that a page contains an error. A flash message should not be the only method used to communicate an error.

Screenshot showing position of flash message

Refer to the flash message documentation to learn how to create flash messages.

Form errors​

When a form contains errors, you should:

  • Add 'Error:' to the beginning of the page title, so screen readers read it out as soon as possible
  • Show an error summary at the top of the form
  • Move keyboard focus to the error summary
  • Use the heading, 'There is a problem' within the error summary
  • Show the same error messages under the inputs as is used in the error summary
  • Link error summary errors to the respective inputs
  • Ensure error messages are descriptive, clearly worded and inform the user how to correct the issue
  • Mark fields with errors as invalid

Error summary​

When a form contains errors, you must show both the error summary at the top of the form and an error message below each input that contains an error. The error summary should be shown when there are form errors, even if there is only one.

There is a problem

Example form with errors
Enter your first name
Enter your last name

Refer to the error summary documentation to learn how to create error summaries.

tip

By using the error-summary helper, errors will be automatically linked to the inputs and keyboard focus will be moved to the summary on page load

Linking from the error summary to each input​

Each error in the error summary must link to the input it relates to. When an error relates to a single input, it should link to that input.

When an error relates to multiple fields, such as day, month, year inputs which make up a date of birth, then link to the first input with an error. If you do not know which input contains an error, link to the first input in the group that has an error.

For inputs that require a user to select one or more options from a list using radios or checkboxes, link to the first radio or checkbox.

Where to put the error summary​

Put the error summary at the top of the form, typically above the first fieldset.

Invalid fields​

Form fields should be individually given descriptive error text which explains in clear, concise language, what the person filling in this form needs to do to resolve the error for this specific field.

If the person is expected to provide information in a specific format, such as an email address, date or postcode, an example should be provided either through help text, or as part of the error message.

Each form helper will allow the error message to be defined by the error helper option. If you're using HTML you will have to refer to each form component's documentation for the correct combination of markup and classes to use.

Avoid messages like:

  • ‘Field cannot be empty’
  • ‘This field is required’
  • ’Invalid value’
  • ’Answer the question’
Enter your first name
Enter an email address in the correct format, like name@example.com

Accessibility considerations​

Pulsar twig helpers automatically include the required accessibility features and should be used as much as possible, if you have to use plain HTML then your implementation must include the same accessibility features. Failure to do this will result in a user interface that may fail an accessibility audit and not provide a sufficient experience for the people using our software.

If you are dynamically toggling the state of an input between valid and invalid without a page refresh, you must ensure you’re toggling the relevant combination of classes and aria attributes where applicable.

Colour​

When a form field is in error state, the label, the field border, and the error message should all use the danger colour. The shade of red used in the danger colour contrast is WCAG 2.1 AA compliant. If you're using the correct combination of markup and error classes as described by the component documentation this should be styled automatically, however if you need to style somthing custom then you can fetch the danger colour from the palette.

.example {
    color: colour(danger);
}

Visual indicator​

All form field errors should be visually marked with the warning icon so that colour is not the only method of differentiating between an error and regular help text.

For regular form layouts, the error message should be placed immediately underneath the related input. If additional help text is required this should be placed underneath the error message.

{{
  form.text({
    'label': 'Email address',
    'id': 'email', 
    'name': 'email',
    'value': 'my-email at hotmail dot com',
    'error': 'Enter an email address in the correct format',
    'help': 'e.g. name@example.com'
  })
}}

Aria-invalid​

Invalid fields should have the aria-invalid="true" attribute applied, this allows assistive technologies to correctly interpret and announce the state of an invalid field.

caution

If you’re not using Twig or React helpers in your UI and are choosing to use plain HTML, it’s your responsibility to use an appropriate label matched to the input with aria-describedby