Alert
What is this?
Alert indicators allow merchants to view semantic messages that are prominent and can be dismissable.
Variants
The alert's tone of voice is either `info` (default), `warning`, `positive`, or `critical`.
Loading...
Action
You can easily add an action into any Alert using the Anchor component.
Loading...
onDismiss
Represents the event of click from the alert dismiss button. To use this feature, define the `onDismiss` property.
Loading...
Usage
import { Alert } from '@vtex/admin-ui'
function Example() {
return <Alert>Order successfully placed</Alert>
}
Props
| Name | Type | Description | Required | Default |
|---|---|---|---|---|
| csx | StyleObject | Custom styles | 🚫 | {} |
| onDismiss | () => void | Action to dispatch on dismiss | 🚫 | - |
| variant | info, positive, warning, or critical | Tone of voice | 🚫 | info |
| children | ReactNode | Component children | 🚫 | - |
| action | AlertActionProps | An action that a user can take upon the alert | 🚫 | {} |
Components
When to use a Toast instead of an Alert?
Choose a Toast for notifications related to the entire page that happen after the page loads and can disappear automatically. Non-dismissive Alerts that indicate progress are the only ones that can appear after the page loads.
Variants
When to use an info, critical, warning or positive Alert?
- Use an info Alert for neutral notifications that don't require attention, such as announcements, product invitations, or task progress. For example, "This release is being published and may take up to 5 minutes".
- Use a critical Alert, usually with a proposed action, when an action has failed due to a technical error or a user error. For example, "There are 2 invoices that could not be processed because of a technical issue" with a Try again button.
- Use a warning Alert when something may not be working as expected or when there is something to be cautious about, usually with a proposed action. For example, "Stores in this account still can't sell to the final customer" with an Activate account button.
- Use a positive Toast for successful actions or messages that don't require attention and further actions. For example, "The performance of this seller improved and now meets minimum requirements" with a View performance button.
When to include an action in an Alert?
The Alert 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.
- Testing a new feature or product.
When should an Alert be dismissible?
- Most Alerts should be dismissible, such as success feedback and product invitations. Alerts should only be non-dismissible when they provide crucial information and its persistence doesn't negatively affect the user experience.
- A warning Alert with a help text that needs prominence should be considered part of the page's content and therefore non-dismissible. For example, "The Application Token will be only displayed once. Make sure to copy and save it in a safe place."
- A critical Alert with an error can be dismissible or not depending on its severity. Errors that block the usage of a page should not be dismissible. Consider the following examples:
- Non-dismissible: "This extension is not available, as payment flags are not enabled in the store." with a Set up payment button.
- Dismissible: "There are 2 invoices that could not be processed because of a technical issue." with a Try again button.
Position
What should be the position of an Alert in a container?
Position the Alert semantically, either directly in the page (global Alert) or inside a card or modal (contextual Alert). Always in the start of the container, right below its header, taking up 100% of the width and respecting the container margins.
What to avoid:
Don't place the Alert inside, above or attached to the Page Header.
What to avoid:
Don't place the Alert inside, above or attached to the Page Header.
Behavior
When should an Alert appear?
Alerts should usually appear as the page loads. Non-dismissive alerts that provide loading feedback, however, can appear right after a merchant's action.
What should be the duration of an Alert?
Every Alert should not be dismissed automatically. For temporary notifications, use a Toast instead.
When should multiple Alerts appear simultaneously?
Avoid displaying more than one Alert at the same time. Prefer to summarize the information in a single Alert. For example, use "There are 10 invoices with recent updates" with a View details button in an Invoices listing page when there have been multiple updates.
Content
What should be the message of an Alert?
- Write a single sentence that is direct and has up to 2 lines.
- Use sentence case, but capitalize proper nouns.
- Critical Alerts should include an action that fixes the issue or at least explain what to do next.
- An info Alert with a product invitation should use a standard message, such as "A new Products experience is available. This version will be discontinued in June 2023." with a Try new version button.
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 processed because of a technical issue" instead of "Error 298dx9283 prevented the invoice from being processed".
What should be the icon of an Alert?
Each Alert variant includes a specific icon according to its semantics. This is the default behavior and should not be customized.