Section Heading
There was a problem below
Please fill in the details below...
The responsive layout is in early preview. Please report any bugs.
Alert
An alert notifies a user to high-priority or time-sensitive information.
- Status
- production
- Version
- 7.0.0
- Import from
@twilio-paste/core/alert— or —@twilio-paste/alert
Chimamanda Ngozi Adichie: Racism should never have happened and so you don't get a cookie for reducing it.
Guidelines#
About Alerts#
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.
Use an alert for one of these types of information:
- Neutral or general information. Use this in most cases where you are notifying a user of a change.
- Warning. Use this for critical information that will help a user avoid an issue.
- Error. Use this for critical information that's preventing a user from continuing a flow and if there's action required on their end to resolve the issue.
Alerts vs. Feedback indicators and dialogs#
To communicate feedback on a user action, use a toast or in-page validation (e.g., full-page confirmation, inline error) instead.
To interrupt a user flow or provide the user with more than one action, use an alert dialog.
Accessibility#
- On all alerts, pass in
role="alert"orrole="status"through props. - Screen readers will announce error and warning alert text immediately. Alerts that persist across multiple pages will announce themselves repeatedly which may become annoying. Consider making alerts in these cases dismissible.
- Render 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.
Our alerts have icons that both announce the type of alert it is to screen readers and visually indicate what type of alert it is. That way the background color isn't the only distinguishing feature between alert types.
Examples#
Here are ways that you can compose neutral, warning, error, and dismissible alerts.
Martin Luther King, Jr.: We may have all come on different ships, but we’re in the same boat now.
James Baldwin: Love takes off masks that we fear we cannot live without and know we cannot live within.
Chimamanda Ngozi Adichie: Racism should never have happened and so you don't get a cookie for reducing it.
Toni Morrison: You wanna fly, you got to give up the shit that weighs you down.
Neutral#
Use a neutral alert to notify a user of a change that's relevant for them to achieve their current goal. Don't use an alert 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"
A notification sent irrespective of the current user goal would likely be ignored, and may even annoy users because it will disrupt their current task and be irrelevant to their current needs.
Set up your contact preferences. You can now set up your contact preferences on your dashboard. Go to contact preferences
Warning#
Use a warning alert to help a user avoid an issue. If the user can take an immediate action to avoid the issue, provide a way to do that.
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".
Some information on this page may be out-of-date. This page was last updated at 9:00 AM PST. We're currently looking into this issue.
Error#
Use an error alert to help a user understand a critical issue at the system level. Provide a way to resolve the issue in the alert.
Be cautious about using an error alert because they can be stressful for a user to see. In most cases, error alerts should be assigned role="error".
There's a good chance you need to use an error alert if both these conditions are met:
- The system-level issue is preventing the user from continuing a flow.
- The user must take an action to resolve the issue.
Please update your billing information or we'll suspend your account on March 2. We couldn't renew your subscription with the information we currently have. Update billing information
Dismissible#
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.
We've enabled new security options for your account. Learn more
Composition Notes#
Keep alert text brief by placing only the highest priority information in an alert. Too much text in an alert can overwhelm a user. A good rule of thumb is to keep alert text to a single line in a desktop-sized container, or limiting it to 90 characters.
Regardless of screen width, the optimal line length is still 45–90 characters. As you test your layout, make sure that text elements stay within this range.
Compose an alert with:
- A title (optional). Bold this text at the beginning of the alert. This should be the most scannable text in the alert.
- Body text. Use the default text style. Provide specificity on the issue and a resolution if applicable via an anchor. Be cautious about using a button in an alert since it may compete with other buttons on the screen and should be used only to trigger an action. If you must use a button, use a small button.
When to Use an Alert#
Place an alert where it makes the most contextual sense. Don't cover other UI elements with an alert.
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.
Your account balance is low and your credit card has expired. As a result we have suspended your account
Do
Use only 1 alert per page. Use 2 alerts only if absolutely necessary and if the alerts are placed in different containers.
Your credit card has expired
Your account balance is low
Your account is suspended
Don't
Don't use more than 2 alerts per page.
Do
Place global alerts at the top of the page. Place all other alerts at the top of the container it relates to beneath the heading.
Billing information
Your credit card is about to expire
Don't
Don't cover other UI elements with an alert.
A call to action Learn more
Do
Use anchors to link to more information that may be helpful for users to resolve or clarify an alert message.
A call to action
Don't
Avoid using buttons in alerts unless it triggers an action.
Do
Be cautious about using alerts since they can be stressful for users to see.
Don't
Don't use alerts to communicate every change in a product (e.g., marketing messages, trial status) so that important messaging isn't diluted.
Anatomy#
| Property | Default token | Modifiable? |
|---|---|---|
| background-color |
| No |
| border-color |
| No |
| border-radius | border-radius-0 | No |
| border-width | Bottom border: border-width-20 | No |
| icon color |
| No |
| icon size |
| No |
| spacing |
| No |
Usage Guide#
API#
Installation#
yarn add @twilio-paste/alert - or - yarn add @twilio-paste/coreUsage#
import {Alert} from '@twilio-paste/alert';const Component = () => ( <Alert variant="error"> <Text>There is an error in the system.</Text> </Alert>);Props#
| Prop | Type | Description | Default |
|---|---|---|---|
| children? | ReactNode | null | |
| onDismiss? | () => void | Create dismissable alerts by providing an onDismiss callback | null |
| role? | string | Provide a specific ARIA role to the alert that overrides the calculated one set by the component | null |
| variant? | string | error / neutral / warning | null |
Changelog
Changelog