Error state

// import one of the following ingredients for the error state pattern
import {Alert} from '@twilio-paste/core/alert';
import {Callout} from '@twilio-paste/core/callout';
import {Toast} from '@twilio-paste/core/toast';
import {HelpText} from '@twilio-paste/core/help-text';

Use an error state after a problem occurs. For example:

• A user tried to submit a form with required fields missing.
• A failed connection terminates a user action.

To proactively call a user’s attention to information that can help them avoid errors or undesirable outcomes, use a warning. For example:

• Telling a user an action might increase their bill.
• Telling a user they’re about to hit a limit.
• Telling a user a selection has notable limitations.
• Telling a user an action could result in lost data.

When developing an error message:

• Tell the user what happened, why it happened, and how to fix it (if they can).
  • If you’re tight on space, prioritize what happened and how to fix it.
  • If you have extra room, explain what happens if the error isn’t fixed.
• Be as specific as possible. Develop a tailored error message for each possible cause.
• Use plain, human-readable language. Prioritize active voice, but consider passive voice when the emphasis should be on the outcome and not who/what caused the outcome.
• Avoid blaming the user. Focus on what the user needs to do to move forward, not what they did not do.
• Avoid certain words. The language we use during an undesirable experience matters. Avoid the following language:
  • Technical jargon. Don’t introduce terms your users may not understand.
  • Negative or alarmist words like: forbidden, illegal, prohibited, valid/invalid.
  • “Please.” It makes the action sound optional.
  • “Sorry.” Overusing it makes it lose its meaning. Reserve this for situations where something highly detrimental has happened, like lost data.
• Place the error message as close to the source of the error as possible.

When possible, use an icon and color to indicate an error. When using only an icon or color, ensure the content clearly indicates something went wrong.

Work with engineers to try to avoid an endless “try again” loop. Explore whether you can offer a series of things to check if the user hits a particular error several times in a row.

Include error codes only when the user can use it to troubleshoot by themselves or by giving the code to customer support. Ensure there is either public documentation or support team documentation that maps error codes to specific resolution instructions before including error codes.

Place error codes at the end of the message inside parentheses.

An empty state is also an error state when content fails to load. Error empty states can result from problems like a system issue or access issue. Error empty states are different from empty states that result from a lack of data to show. If the error empty state occurs in a small component (a card, for example), prioritize communicating how to fix the problem.

When cards are used as part of a dashboard to display metrics, error states can occur on individual cards because the data populating a particular card isn’t available. Since these cards are usually small, use error iconography paired with a 3-5 word error message.

Alert

• Alerts communicate a critical issue at the system level, like site-wide service disruptions, active incidents, or expired billing information.
• Alert error messages do not result from a user action.

Callout

• Callouts communicate:
  • An error specific to a particular section of a page, or that applies to a whole page.
  • An error summary of multiple errors on the page. When used for form validation, still include the inline error messages.
  • Use Callouts for situations like operation failures with multiple pieces of information, or a form submission missing many required fields.
• Callout error messages can result from a user action, but don’t have to.

Toast

• Toasts communicate brief, easily comprehended error messages that are not the user’s fault, like a failed connection.
• Toast error messages usually result from a user action.
• Toast error messages should never automatically disappear.

Help Text

• Help Text communicates contextual errors, like field validation.
• Help Text can result from a user action, but doesn’t have to.

• Alert
• Badge
• Singleselect Combobox
• Multiselect Combobox
• Date picker
• Disclosure
• File picker
• File uploader
• Form
• Form pill group
• Help text
• Input
• Radio button group
• Radio group
• Select
• Textarea
• Time picker
• Toast