- Why this is important
- Use when…
- Do not use when…
- Provide good instructions so errors can be avoided.
- Ensure the user can use the form’s submit button, even if the form is in an error state.
- Ensure that errors are identified and explained.
- Present the error message after the error occurs, not before or in the middle of completing the field.
- Present the error message text directly after the field in error visually and in the tab order.
- Ensure that invalid fields are marked as invalid using aria-invalid.
- Ensure that ARIA Alerts or Live Regions are being used to identify errors.
- Do not use color alone to indicate an error.
- Follow error message content standards.
- Display the error until it is corrected.
- Ensure the user has the time necessary to correct the error.
- Ensure that the error messaging visual design is consistent across form fields.
- Ensure there is a link to help or the documentation available somewhere on the page.
Field-level validation is the act of using a scripting language to detect and report errors to the user while they’re still in the context of the field that has the error.
Field-level validation is overwhelmingly used to catch structural validation issues. Field-level validation is good for things like “this date is formatted incorrectly” or “you can only choose up to three of these checkboxes”. It is generally not good for catching business rules such as “Susie can’t have this mortgage because her credit score is too low” or “you can’t submit this form because you already have one processing”.
Field-level validation can’t be asynchronous from the user’s point of view – you can’t notify the user two hours later that a field is wrong, you have to catch it immediately or allow the form to process.
- Field-level validation doesn’t replace good instructions.
- Field-level errors should report
- Instructions should clearly state what the error is.
- Accessibility requirements should be met.
This pattern applies to any form field that can be in an error state. This includes:
- Date fields, including date pickers, and the following
- 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
- Web addresses and
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 as quickly as possible.
- If an error can’t be corrected by the user, we must tell the user what to do next.
- The form includes validation at the field level.
- The form includes validation at the page level and you need to communicate which fields must be changed for the page to validate.
Do not use when…
- The error is at the server-level (i.e. the server is not responding).
- The error is not specific to a form field that needs correction (i.e. “someone deleted this object while you were busy editing it”).
- 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. For example, if you want users to enter a date in a specific format, tell them that in instructions up-front before they enter the field. Don’t wait until they’ve committed the error to tell them what the appropriate date format is.
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 when the page doesn’t properly validate.
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.
Present the error message after the error occurs, not before or in the middle of completing the field.
This is a famous problem with email address fields: you start to type in the field and, because you haven’t put an @ symbol or a period in the field yet, the field is immediately put into an error state until you finish typing.
Picture someone at a store asking you for your email address and as soon as you start to say it they start yelling “OMG WHY HAVEN’T YOU GIVEN IT TO ME YET?!?” That’s what immediate error states feel like to users. (It’s even worse for people using screen readers where, if coded rudely, the error is yelled out at every keystroke.)
onblur, or at the moment the field loses focus. That way the user can complete the field and then learn of the error.
Present the error message text directly after the field in error visually and in the tab order.
A keyboard user may be tabbing from field to field to quickly and easily complete a form. (They may or may not also be a screen reader user.) When the user tabs out of a field with invalid content, display the error text directly below or next to the field and next in the tab order. The goal is to draw the user’s attention to the error before they leave the context of the current field and go to the next one.
Text doesn’t usually show up in the tab order of a form, especially if the form is in a
<form> element, so if creating your own component you may need to add the content to the tab order and ensure it’s read out by screen readers.
Associate the error message to the field by using the
aria-describedby attribute. This allows you to associate the message to the field without impacting the label. If that’s not possible, you can use the
aria-labelledby attribute to modify the label while the error is an issue.
Ensure that invalid fields are marked as invalid using
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.
Users with Color Vision Deficiency (CVD) may not be able to tell that you turned the border red and added some red text below the field. Ways to mitigate this include:
- Include an error icon (with appropriate alt text) with the error to help users identify it.
- Include the word “Error:” in front of the message, and make it stand out using bold or some other non-color technique.
- Ensure that if a border’s color has changed, something else (most frequently its width) has as well.
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 error message
onfocus or when the user reenters the field, because there may be information in the error message that the user needs to correct the error. Even if there isn’t, providing the error state until the next time the field is blurred ensures that if the user steps away and comes back they can see the error is unresolved.
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 accessibility guidelines 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 text errors one way in one part of the application and a different way somewhere else. Don’t style number errors significantly differently than you style text errors, especially within the same form.
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.
The following Web Content Accessibility Guidelines impact this pattern:
- 1.1.1 Non-text content (if an icon is used to indicate an error)
- 1.3.3 Sensory Characteristics
- 1.4.1 Use of Color
- 1.4.3 Contrast (Minimum)
- 2.1.1 Keyboard
- 2.1.2 No Keyboard Trap
- 2.2.1 Timing Adjustable
- 2.4.3 Focus Order
- 3.2.4 Consistent Identification
- 3.1.3 Unusual words
- 3.3.1 Error identification
- 3.3.3 Error suggestion
- 3.3.5 Help