1. Home
  2. :
  3. Roles
  4. :
  5. UX Designer
  6. :
  7. Error Messaging Patterns
  8. :
  9. Page-level validation and error messaging

Page-level validation and error messaging

Page-level validation is the act of ensuring that a full page of information is valid according to both structural validation and business rules (where possible) after the user hits the form submit button but before the information is treated as completed and valid.

Examples of page-level validation include:

  • Confirming that all required fields have been completed.
  • Confirming that business logic to ensure a valid form is completed. Examples include:
    • The user is being asked to schedule two events. Page-level validation is used to ensure that they are not scheduled for the exact same time.
    • During registration, the user chooses a username already in use. Page-level validation ensures that the user is notified they have chosen an existing username and have to pick a different one.

Page-level validation doesn’t mean “the page doesn’t talk to the server”. As in the username example above, page-level validation often requires validating against existing data or logic to ensure that the user can correct the problem without leaving the page.

Page-level validation can’t be asynchronous from the user’s point of view – you can’t notify the user two hours later that a form was submitted with invalid information. You have to catch it immediately or allow the form to process.

TL;DR

  • Page-level validation doesn’t replace good instructions.
  • The page should list all errors in an alert at the top of the page.
  • The alert should link to each error on the page.
  • Instructions should clearly state what the error is.
  • Accessibility requirements should be met.

Components involved

  • Alert components, specifically banners
  • Customized validation of form components
  • Checkboxes
  • Date fields, including date pickers, and the following input types
    • date
    • datetime-local
    • month
    • time
    • week
  • Email address fields
  • File select (for upload)
  • Number fields
  • Radio buttons (generally only if nothing is selected by default)
  • Search fields (if entries are being validated prior to submit)
  • Select menus, including multi-select menus
  • Telephone numbers
  • Text fields including password fields
  • Web addresses and url fields

Pattern description

This pattern applies to any form where page-level validation is necessary. It is not specific to any set of fields, and could apply to fields (like select menus) where field-level validation is rarely performed.

This pattern describes where and when messaging should occur. It is descriptive, rather than prescriptive – as long as you align with the accessibility requirements described below, the visual design and structure may be different from implementation to implementation (within reason – see the bits about consistency below).

Why this is important

  • If an error can be corrected by the user, we must tell the user how, and do so as quickly as possible.
  • If an error can’t be corrected by the user, we must tell the user what to do next.

Use when…

  • The form includes validation at the page level. (Note: almost all forms include validation at the page level.)

Do not use when…

  • The error can be caught and addressed at the field level (i.e. they entered a date in an invalid format). Use the Field-level validation and error messaging pattern instead.
  • The error is at the server level (i.e. the server is not responding). Use the server-level validation pattern instead.
  • The error is not specific to a form field that needs correction (i.e. “someone deleted this object while you were busy editing it”). Use the server-level validation pattern instead.
  • The scenario is not an error.

How to use

Provide good instructions so errors can be avoided.

Error messaging does not replace good form design.

  • Ensure that required fields are marked as required as outlined in the Required Fields portion of the design system.
  • Ensure that any business logic the user needs to be aware of is described at the top of the form.
  • Describe what will happen after the user submits the form.

For forms where the user is submitting legal, financial, or data-modifying transactions (at minimum), the user should be given the option to do on of the following:

  • Review and confirm the transaction before submitting.
  • Reverse the transaction after submitting.
  • Be informed of errors the system identified and correct the errors before submitting.

Ensure the user can use the form’s submit button, even if the form is in an error state.

Some sites insist on disabling the submit button until the user has corrected all the errors on the page. This would be fine if we could be confident that every user is going to recognize that at least one form field is in an error state and correct it before trying to submit. That rarely happens. 

When the button is disabled, users can’t submit the form to find out what’s wrong. Even if your error design is impeccable, the user may be able to overlook or miss it. The error may be in a field that’s off the page or otherwise not visible. The user may have low vision and not be able to easily visually identify errors. It’s also possible that user is experiencing change blindness (a form of inattentional blindness) and doesn’t recognize that a field has been marked invalid.  

Worse, screen readers skip disabled elements, so a screen reader user tabbing around to find the submit button will never find it, and will assume your form is broken before they’ll assume they’ve done something wrong.

Instead of disabling the button, allow the user to click the button, then display a page-level error message in a banner as described below when the page doesn’t properly validate.

Update the page title when the page is in an error state.

If the page is in an error state, update the page <title> tag to indicate that it’s in an error state. This accomplishes two things:

  • When the page reloads after the errors are discovered, screen reader users immediately hear that there’s an error that needs to be corrected.
  • The user can see in the browser tabs that the page is in an error state, so if they’ve switched to a different tab they have a visual cue that the form they submitted requires additional work.

Ensure that errors are identified and explained.

It sounds obvious that error messaging requires providing an error message, but sometimes complex interactions get ignored or lost during the process of devising error messages.

For example, when creating an Atlassian Confluence page, the user can’t put content that’s in a code block into a link. (Why is a question for a different day, as it is valid HTML.)

Instead of notifying the user that it’s an invalid action, the system just ignores the user’s attempts to create the link, either by disabling the link icon or by ignoring the ctrl-k keyboard stroke. This leaves the user baffled, confused, or annoyed.

Take the user to the explanation of the error(s).

When the user submits a form, they are indicating they think they’re done.

It is not enough to turn fields red and add error test to the affected fields.

  • Depending on the size of the form and the scroll position, the user may not be able to see the fields in error.
  • Even if the fields are in view, the change in state from default to error may not be enough to draw the user’s attention to the errors (especially if they have Color Vision Deficiency (CVD) and can’t differentiate the color red from our usual dark grey text color).

When the page is submitted and returned with errors:

  • Add an error alert to the top of the form.
    • Ensure the error message statement is in an ARIA region / live region, so that screen reader users can quickly locate the area.
  • Move the user’s focus to the alert at the top of the form.

Alternatively, you could use a modal dialog or a Javascript alert message to notify the user that there are errors and how to find them.

On the positive side, Javascript alert messages are easily identified by a screen reader and the user is notified immediately.

On the negative side, a dialog requires the user to remember where the errors were once they close the dialog, which could be challenging on large forms, complex forms, or for users with cognitive and neurological disabilities.

If you’re using an alert dialog component (as compared to the Javascript-triggered system dialog) you also have to make sure that the dialog is accessible. Ensure that the ARIA role alertdialog is used. Read more about alertdialog on ARIA18: Using aria-alertdialog to Identify Errors on the W3C website.

Describe the error(s) in detail in the alert and in the field-level validation.

The error alert should include content indicating:

  • That an error occurred.
  • What the errors are. (Preferably this includes a link to each error. If you can’t link to each error, tell the user how to identify it, i.e. “Please complete all fields marked with ‘Error’”. )
    • List the errors in the order they display on the page. Nobody wants to play “Where’s Waldo” with the error messages.
    • Use the same field labels that are used on the page to describe which fields are in error.
  • What the user needs to do to fix them.

For each field in error, the field should be in an error state (see Field-level validation and error messaging) and the field-level error should describe the issue. Example error messages include:

  • First name field may not be blank.
  • This user name is already in use. Choose a different user name.
  • Birth date must occur before anniversary date.
    • On the anniversary date field, it would then say “Anniversary date must occur after birth date.”

Ensure that invalid fields are marked as invalid using aria-invalid.

This attribute ensures that people using assistive technology can be programmatically notified that the field is in an error state.

Ensure that ARIA Alerts or Live Regions are being used to identify errors.

This ensures that people using screen readers are notified that the page changed when the error was added to the document object model (DOM).

See Using ARIA role=alert or Live Regions to Identify Errors for more on this topic.

Do not use color alone to indicate an error.

Ensure that the alert is an error alert with an icon or that the text clearly indicates that an error occurred. (The icon, obviously, should have appropriate alt text to indicate that it’s an error.)

See Field-level validation and error messaging for field-level specific formatting guidelines.

Follow error message content standards.

  • Do not use sensory characteristics in the text of the error. “Correct the field in red” is right out.
  • Ensure that the reading level is appropriate for the audience. (Also, don’t assume that your audience is 100% college-educated native English speakers.)
  • Ensure that any technical terms or jargon are either removed or explained.
  • Provide suggested values for an incorrect field if possible. For example, if the user entered “December” for the month and the form was expecting “12”, the error message should explain that you’re looking for a numeric value.
    • Best practice: look at what they entered and suggest an alternative, i.e. “Do you mean ’12’?”

Display the error until it is corrected.

Don’t clear the alert from the top of the page until the user re-submits the form.

Ensure the user has the time necessary to correct the error.

If the form in question is on a timed page, ensure the user has enough time to correct errors. For example, a login page may automatically refresh after 2 minutes to protect the user’s security. Someone using a mouth stick may need more than 2 minutes to navigate back to the field and retype their username and password. Follow the accessibility guidelines listed below to ensure that a user has not only enough time to type in the fields the first time, but also enough to correct errors.

Ensure that the error messaging visual design is consistent across form fields.

Once you have chosen a standard for a specific application, ensure that it’s consistently used within a form and across forms. Don’t style the alert in different ways or put it in different places without a good contextual and business-goal-related reason to do so.

Ensure that if the user resizes the page or zooms in to up to 400% the alert content is still fully readable.

If the user resizes the page to smaller-than-expected sizes or is zooming in for low-vision reasons, they should still be able to read the error message alert and any error messages at the field level. See Understanding Success Criterion 1.4.10: Reflow for more details.

Ensure there is a link to help or the documentation available somewhere on the page.

If the user needs more information, they should be able to get to it quickly and easily. If there’s a walkthrough or other descriptive content available on your application, link directly to the appropriate information page.

Accessibility guidelines

The following Web Content Accessibility Guidelines impact this pattern:

Examples and counter-examples

TBD

Additional resources

How to Provide Accessible Form Error Identification by Jonathan Avila at Level Access