View source for Field-level validation and error messaging

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.
==TL;DR==
* Field-level validation doesn’t replace good instructions.
* Field-level errors should report onblur 
* Instructions should clearly state what the error is
==Pattern description==
* This pattern applies to any form field that can be in an error state. This includes:
* 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
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. 
===Use when…===
* 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.See [unwritten pattern] for more details.

===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.) 

In Javascript terms, we recommend validating the field onblur, or at the moment the field loses focus. That way the user can complete the field and then learn of the error. 

Side note: for things like creating a password, it may be helpful to provide a guide to the side of the field listing the requirements and whether the user has reached them… so long as you don’t code it to yell all the requirements at a screen reader user every time they hit a keystroke.

===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 tag, 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.
===Ensure that invalid fields are marked as invalid using aria-invalid.===
This 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 [https://www.w3.org/WAI/WCAG21/Techniques/aria/ARIA19 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.===
These vary from organization to organization but often include:
* 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 [https://webaim.org/articles/motor/assistive#mouthstick 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 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. 
==Accessibility guidelines==
The following Web Content Accessibility Guidelines impact this pattern:
* [https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html 1.1.1 Non-text content] (if an icon is used to indicate an error)
* [https://www.w3.org/WAI/WCAG21/Understanding/sensory-characteristics.html 1.3.3 Sensory Characteristics]
* [https://www.w3.org/WAI/WCAG21/Understanding/use-of-color.html 1.4.1 Use of Color]
* [https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html 1.4.3 Contrast (Minimum)]
* [https://www.w3.org/WAI/WCAG21/Understanding/keyboard.html 2.1.1 Keyboard]
* [https://www.w3.org/WAI/WCAG21/Understanding/no-keyboard-trap.html 2.1.2 No Keyboard Trap] 
* [https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html 2.2.1 Timing Adjustable] 
* [https://www.w3.org/WAI/WCAG21/Understanding/focus-order.html 2.4.3 Focus Order]
* [https://www.w3.org/WAI/WCAG21/Understanding/consistent-identification.html 3.2.4 Consistent Identification]
* [https://www.w3.org/WAI/WCAG21/Understanding/unusual-words.html 3.1.3 Unusual words]
* [https://www.w3.org/WAI/WCAG21/Understanding/error-identification.html 3.3.1 Error identification]
* [https://www.w3.org/WAI/WCAG21/Understanding/error-suggestion.html 3.3.3 Error suggestion]
* [https://www.w3.org/WAI/WCAG21/Understanding/help.html 3.3.5 Help]

[[Category:Design]]