Errors will always occur. This pattern provides general guidelines on how to surface the many types of errors and warnings that occur in the app.
When writing an error or warning message, consider these questions:
Each of these is explained in more detail. For needing a component quickly, consider these common scenarios.
They can be used to:
Form errors are among the most common type of errors. Each individual component page provides specific styling and text location. It is recommended to also use a Banner as a summary when multiple errors exist.
This validation occurs after a user has hit a save or submit button. These errors are paired with Banners and individual form field errors.
When format requirements exist for a field (such as the
@ in an email input), validating the form element after a user has left focus can help resolve errors.
When to use validation before submission:
When an Input has known formatting requirements. If the requirement is ambiguous to a user (e.g. password requirements), add a field description.
In the initial user interaction, validate only after a user has left focus on the field and if the user entered anything.
When a user interacts with an errored field, validate after each keystroke. This helps the user identify when the user has met the field requirements.
When to avoid validation before submission:
It is recommended to add a Banner at the top of a form that has errors. If the form is the main content of the page, it follows the Page-level guidelines. Otherwise, it appears wherever the top of the form is.
The Banner should only appear after a validating on submit. Validations before submission do not need a Banner.
The summary should list out each of the errors encountered on the page.
In general, the summary should not be used alone. Inline help should be added when possible.
System errors can typically be described as 400 or 500 type errors. If there is a place for it on the page, it is preferred to integrate an Empty State into the section. Otherwise, using a Toast is preferred over components such as the Banner or Announcement.
When a system error is the apps fault, take responsibility.
If there is an HTTP response, place it at the end of the body content.
When using the Toast to present an error, it should persist on the page.
When it is possible to determine the solution, provide it to the user. For example, a 401 error resulting from not being logged in.
App-level messages are used to convey a status relevant to the entire experience, represented with an Announcement. These are not used in specific products within the platform. Some examples might include a sandbox environment message and a scheduled downtime notice.