Toast
What is this?
Toast indicators allow merchants to receive instant feedback that is usually temporary and can always be dismissed.
Variants
The toast's variant is either info (default), critical, warning, or positive, and is adjustable using the variant prop.
Non-dismissable
Toasts are dismissable by default. The dismissable prop controls this behavior.
Action
Display a button allowing the toast to have an action.
Replacing toasts
You can assing a key to your toasts. Only a single toast with the given id is visible at once. Use it to reduce the number of toast on your app.
Usage
To show toasts you must call the useToast hook.
import { useToast } from '@vtex/admin-ui'
function YourComponent() {
const showToast = useToast()
showToast({
message: '...',
})
// ...
}
The hook consumes a context provided by the ToastProvider. You must wrap the app root by the provider, it show below your ThemeProvider.
// App root file
import { ToastProvider, ThemeProvider } from '@vtex/admin-ui'
function Root() {
return (
<ThemeProvider>
<ToastProvider>
{...}
</ToastProvider>
</ThemeProvider>
)
}
Props
Because the way of rendering a Toast on admin-ui is by calling the function returned by the useToast hook, these are the properties that you can pass to the function returned params.
| Name | Type | Description | Required | Default |
|---|---|---|---|---|
| message | ReactNode | Message displayed to the end-user. | ✅ | - |
| variant | critical, info, warning, positive | Toast's variant. | 🚫 | info |
| duration | number | How long the toast should be apparent, in milliseconds. | 🚫 | 10000 |
| dismissible | boolean | Whether the toast can be dismissed or not. | 🚫 | false |
| action | { label: string, onClick: () => void } | Toast's actions' props. | 🚫 | undefined |
| key | string | Toast's key. | 🚫 | undefined |
Components
When to use an Alert instead of a Toast?
Choose an Alert when the notification loads with the page content and depends on user action to disappear. For example, the Order details page continues to display the Alert with an error in the order until it is solved. Non-dismissive Alerts that indicate progress are the only ones that can appear after the page loads.
When to give feedback in a Toast or in the container itself?
- Give (non-contextual) feedback in a Toast when the message is temporary and doesn’t require much attention from the merchant.
- Give (contextual) feedback in the container itself when the message is permanent, very detailed or easier to understand in a contextual position. In these cases, use one of the following options:
What to avoid:
- Don't use Toasts for permanent or detailed messages, as they are not easily discoverable by merchants.
Variants
When to use an info (default), critical, warning or positive Toast?
- Use an info Toast for messages that don't require immediate attention and don't have clear semantics. For example, There are 5 new transactions, with a View new transactions button, when the merchant is viewing a page with outdated information.
- Use a critical Toast when an action fails due to a technical error or a user error, usually with a proposed action. For example, "The font could not be deleted because it's used in styles. Please remove it from styles and try again" with a View styles button.
- Use a warning Toast after a successful action when there is something to be cautious about, usually with a proposed action. For example, The product was saved with 5 issues and a Fix issues button.
- Use a positive Toast to indicate success. If the action takes a while to process, use a positive Toast for the submission itself and an info Alert to indicate progress. For example, Product created successfully in a positive Toast and Product indexing in progress in an info Alert.
When to include an action on a Toast?
The Toast message should be as brief as possible, so include an action to complement it when needed. Examples include:
- Providing more details in a modal or related page.
- Retrying a failed action.
- Undoing a successful action.
- Focusing on the first error in a form with issues.
- Refreshing outdated information in the page.
When should a Toast be dismissible?
Always. For non-dismissible notifications, use an Alert instead.
Position
What should be the position of a Toast in a Page?
Considering left-to-right interfaces, the Toast should pop from the bottom of the screen and rest on the lower right-hand corner. This is the default behavior and it should not be customized.
Behavior
When should a Toast appear?
A Toast should appear immediately after the action is triggered (merchant clicks on Save) or the loading feedback is over (loading Button stops spinning).
What should be the duration of a Toast?
- Temporary Toasts should take between 5 and 10 seconds, following an average of 3.5 milliseconds per character.
- Permanent Toasts should only be used when the message requires the merchant’s attention or when they are not expecting it. This includes:
- Error Toasts.
- Warning Toasts.
- Toasts that aren’t immediate results of a merchant’s action.
When should a Toast appear?
Avoid displaying more than one Toast at the same time. Prefer to summarize the result of an action in a single Toast. For example, use 34 products successfully saved when multiple products are edited simultaneously in a bulk action.
Content
What should be the message of a Toast?
- Write a single sentence that is direct and has up to 2 lines.
- Use sentence case, but capitalize proper nouns.
- Critical Toasts should include an action that fixes the issue or at least explain what to do next.
What to avoid:
- Don't write text longer than 240 characters. Prefer to include an action that complements the message when needed.
- Don't use personal pronouns.
- Don't use technical language. For example, prefer using The invoice could not be sent because of a technical issue instead of Error 298dx9283 prevented the invoice from being sent.
What should be the icon of a Toast?
Each Toast variant includes a specific icon according to its semantics. This is the default behavior and should not be customized.