Usage
Use an alert when the user must acknowledge information or make a choice before proceeding — confirming a destructive action, responding to a critical error, or providing required input. Keep it focused: a clear header, a short description, and up to two or three actions.
- Save alerts for moments that genuinely matter – a destructive action, a critical error, or a choice the user really can’t skip.
- Use short, plain-language for the header and description.
- Use clear, action-specific button labels such as “Delete” or “Discard” so users know what they’re choosing without re-reading the message.
- Make destructive actions stand out in red, and always give users a safe way out alongside them.
- Use the stacked layout when labels are long or there are three actions.
- Don't use alerts for non-critical or passive messages (use a banner or toast).
- Don't include more than three actions.
- Don't write long descriptions.
- Don't use an alert purely for confirmation of success (use a toast).
- Don't put the destructive action where it’s easy to tap by mistake.
Usage comparison
|
Component |
Interruption |
Blocking |
Placement |
Key difference from Alert |
|---|---|---|---|---|
|
Alert |
High |
Yes |
Centered, overlays entire screen with scrim |
– |
|
Banner |
Low |
No |
Anchored to bottom of screen |
Sits quietly in the flow — no response needed |
|
Toast |
Low |
No |
Floats above content, near the bottom of the screen |
Auto-dismisses; not persistent and not tied to a specific element |
Design properties
| Property | Values | Default |
|---|---|---|
| Show Fields Boolean | true | false | undefined |
| Stacked button Variant | True | False | True |
Types
Horizontal actions
Two actions sit side by side. Use for simple binary choices with short labels.
Stacked actions
Actions stack vertically. Supports up to three, including a destructive option. Use when there are three actions, or when labels are too long to sit by side.
With input
Adds one or two text fields inside the alert. Use when the decision needs quick input.
Behavior and interaction
- The background is dimmed and non-interactive. To dismiss the alert, the user has to choose one of its actions.
- Tapping the scrim does not dismiss the alert. It only goes away once the user selects a button.
- Every button resolves the alert. The destructive action is visually distinct and should always be paired with a safe or cancel option.
- Fields accept input right inside the alert. Where it matters, validate that input before letting the user confirm.
- Only one alert appears at a time. If another is triggered, it waits until the current one is resolved.
- The header and description are editable text. Keep them short so the alert stays centered and compact.
Positioning
- The alert appears in the center of the screen, sitting above everything else.
- A scrim covers the content behind it, so attention stays on the alert and the rest of the screen reads as inactive.
- It stays put in the center and doesn’t move or scroll with the content.
- Only one alert shows at a time. Never stack or queue several at once.
Related components
Changelog
|
Date |
Version |
Notes |
|---|---|---|
|
Sept 10, 2026 |
1.0.0 |
Initial draft of component guidance |