Alert

<Alert variant="warning">
    <strong>Chimamanda Ngozi Adichie:</strong> Racism should never have happened and so you don't get a cookie for reducing it.
</Alert>

Use an Alert to notify a user about high-priority or time-sensitive changes in the system. Alerts communicate system-level information that isn't triggered by a user action. To decide if an Alert is the right component, check Alert vs. Callout vs. Toast vs. Help Text.

Use an Alert for one of these types of information:

• Neutral or general information. Usually information about a change users need to know about.
• Warning. Critical information that will help a user avoid an issue.
• Error. Critical information that's preventing a user from continuing a flow and if there's action required on their end to resolve the issue.

• Pass in role="alert" or role="status" through props. Otherwise, the default role is status for neutral alerts and alert for warning and error alerts.
• Screen readers announce error and warning alert text immediately. Alerts that persist across multiple pages announce themselves repeatedly which may become annoying. Consider making alerts in these cases dismissible.
• Show an alert only when it's needed. Assistive technologies will be able to read a visually hidden element. Don't visually hide an alert and then make it visible through client-side code.

Alert uses multiple methods to indicate type.

• Icon. An icon visually indicates the type, and announces the type to a screenreader.
• Color. Each type is a different color.

Use a neutral Alert to notify a user of a change that's relevant for them to achieve their current goal. Don't use it to communicate general promotional information.

In most cases, a neutral Alert should be dismissible (i.e., have a close button) and should be assigned role="status".

You may use the Text primitive as a child of Alert, but if you do, be sure to pass color="inherit" for neutral alerts.

<Alert variant="neutral">
    <strong>Set up your contact preferences.</strong> You can now set up your contact preferences on your dashboard. <Anchor href="#">Go to contact preferences</Anchor>
</Alert>

Use a warning Alert to help a user avoid an issue.

A warning Alert should provide explain the possible issue, what to do, and what happens if they don't. If the user can take an immediate action, provide a way to do it.

Be cautious about using a warning Alert because they can be stressful for a user to see. In most cases, a warning Alert should be assigned role="alert".

You may use the Text primitive as a child of Alert, but if you do, be sure to pass color="inherit" for warning alerts.

<Alert variant="warning">
    <strong>Some information on this page may be out-of-date.</strong> This page was last updated at 9:00 AM PST. We're currently looking into this issue.
</Alert>

Use an error Alert to help a user understand a critical issue at the system level, like site-wide service disruptions, active incidents, or expired billing information. When possible, provide a way to resolve the issue in the alert.

In most cases, error Alerts should be assigned role="alert".

For additional guidance on what kind of component to use, use the Alert vs. Callout vs. Toast vs. Help Text guide. For additional guidance on how to compose error messages, refer to the error state pattern.

You may use the Text primitive as a child of Alert, but if you do, be sure to pass color="inherit" for error alerts.

<Alert variant="error">
    <strong>Please update your billing information or we'll suspend your account on March 2.</strong> We couldn't renew your subscription with the information we currently have. <Anchor href="#">Update billing information</Anchor>
</Alert>

Add a close button to the alert if it doesn't communicate a persistent status of the system or the account. If you make an alert dismissible, provide another way for the user to retrieve the alert information.

Don't add a close button to the alert if all these conditions are true:

• The alert communicates a persistent status of the system or the account.
• The information is relevant to the user's goals on the page(s) the alert is on.
• The user wouldn't be able to access the information in the alert if it were closed.

Keep in mind that the longer an alert is present, the more it starts looking like part of the page and loses its interruptive intent. This might make users start to ignore important alert information.

<Alert onDismiss={() => alert('dismissed')} variant="neutral">
    We've enabled new security options for your account. <Anchor href="#">Learn more</Anchor>
</Alert>

To internationalize an Alert, simply pass different text as children. The only exceptions to this are the labels for both the dismiss button and the variant icons. To change the dismiss button's label text, use the i18nDismissLabel prop. To change the label of a variant's icon, use the matching i18n prop for the variant. For an error variant, for example, set the i18nErrorLabel prop.

<Alert onDismiss={() => alert('fermée')} variant="warning" i18nWarningLabel="(avertissement)">
  C&apos;est une alerte d&apos;avertissement.
</Alert>

Keep content brief by placing only the highest priority information in an Alert. A good rule of thumb is to keep text to a single line in a desktop-sized container, or limit it to 90 characters.

Compose an Alert with:

• Title (optional). Bold the text at the beginning of the Alert. The title should be concise and convey the essence of the issue.
• Body text. Use the default text style. Limit body text to 1-2 sentences and do not repeat information contained in a title. Explain what happened, and if something is wrong, how to fix it. When possible, include what happens if they don't take action. If the resolution requires going to a different page, include an Anchor. Use Buttons sparingly, since they may compete with other Buttons on the screen. Only use a small Button if it will trigger an action.
• Full punctuation. Use periods after full sentences. Avoid using exclamation points.

Active voice is generally preferred (for example, "You updated the API."). However, passive voice is acceptable for alerts related to whether a system action occured or not (for example, "API was updated.").

Alert

• Alerts communicate information relevant at the system level.
• Do not use an Alert in response to user action.

Callout

• Callouts communicate information particular to a section of a page, or information that applies to a whole page.
• Use a Callout when there are multiple pieces of information to convey. For example, an error summary.
• Callouts can result from a user action, but don’t have to. Therefore, they can include either static or contextual content.

Toast

• Toasts communicate brief, easily comprehended messages.
• Toasts generally result from a user action.
• If the message is contextual or specific to a particular part of a page, consider Help Text or a Callout.
• Do not use a Toast if the message is longer than two sentences (~140 characters). Use a Callout instead.
• Do not use a Toast if there is more than one anchor or button. Use a Callout instead.

Help Text

• Help Text communicates contextual responses.
• Help Text can result from a user action, but don’t have to.

Place an Alert where it makes the most contextual sense. Don't cover other UI elements.

In general, the persistence and behavior on scroll of an Alert should match the element it's scoped to. For example, if an Alert is scoped to a navigation bar that is sticky on scroll and persists across several pages, the Alert should similarly be sticky and persist across several pages. However, don't persist the Alert across too many pages in a user session since it may lose its interruptive intent.