Toast
Toasts contain updates or messages about the status of an application’s process.
Anatomy
- Container: Rectangular container that houses the icon and text for toasts.
- Icon: An Icon is optional and indicates the status of the message being displayed.
- Text: Description text for explaning what's going on with a process that just occurred.
- Action Link: Optional link for directing users to find helpful information regarding the action they just took.
- Close Button: Close Button is optional and are provided when a Toast doesn't have a timer to close itself.
Usage Guidance
- Toasts should communicate information about the status of an application’s process, like confirmation that a task has been successfully submitted.
- They are low-emphasis and meant to be temporary, but can also be dismissed manually with a Close Button.
- Toasts should overlap and visually look like they are in front of other UI elements without blocking important actions.
- Action Links should be short. Including a non-required action, such as “View More,” is optional.
- For more information on Toast placement, please reference the Notification Pattern Guidance. For help deciding if a Toast is the best component for your use case, reference this decision tree.
When to Use
- Use Toasts when communicating updates about the process of an application.
- Use Toasts for lower priority messages that do not require user action.
When to Use Something Else
- Consider using Banners if communicating messages about system errors or alerts.
- Consider using Dialogs when informing users about critical information that requires user action or decision.
| Type | Emphasis | Purpose |
|---|---|---|
| Toasts | Low | Although Toasts communicate low priority information, user action is still required to dismiss Toasts. |
| Banners | Medium | Banners should be used for messages about errors and alerts. They do not disappear unless the user resolves the required action. |
| Dialogs | High | Dialogs are reserved for messages of the highest priority. They command user action. |
Examples
Basic Usage
Below are examples we expect will work for most use cases. Note that all examples include icons as they are an important signifier to communicate meaning. For this reason, Toast notifications should always include an icon.
Complete Example with Popper
We use Popper to position Toast. Here's an example of how to use them together.
Success
Error
WithCloseButton
With an Action Link
With an Action Link and CloseIcon
With RTL
Component API
Toast
Layout Component
Toast supports all props from thelayout component.
Props
Props extend from div. Changing the as prop will change the element interface.
| Name | Type | Description | Default |
|---|---|---|---|
icon | | The icon of the Toast. | |
iconColor | | string | The color of the Toast icon. | |
children | string | The text of the Toast message. | |
onClose | () => void | The function called when the Toast is closed. | |
onActionClick | () => void | The function called when the Toast action is clicked. | |
actionText | string | The text of the Toast action. | |
model | TModel | Optional model to pass to the component. This will override the default model created for the component. This can be useful if you want to access to the state and events of the model, or if you have nested components of the same type and you need to override the model provided by React Context. | |
elemPropsHook | <TProps>( | Optional hook that receives the model and all props to be applied to the element. If you use this, it is your responsibility to return props, merging as appropriate. For example, returning an empty object will disable all elemProps hooks associated with this component. This allows finer control over a component without creating a new one. | |
as | React.ElementType | Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | div |
ref | React.Ref | Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If |
Accessibility Guidelines
- When a Toast is displayed, make sure this is announced to users using a screen reader.
- A Toast must persist visually until a user interacts with it.
- Toasts should be consistently placed so users can reliably navigate to them.
- Avoid displaying a Toast on page load.
Content Guidelines
- When writing Toasts, refer to the Tooltips and Toasts section of the Content Style Guide.
Can't Find What You Need?
Check out our FAQ section which may help you find the information you're looking for.
FAQ Section