Alert

• Explain a problem where it happened and offer the fix next to it, such as a failed payment with a Retry button.
• Confirm that something worked, in place, by switching the same alert from danger to success.
• Warn before something might go wrong, such as a card that expires in six days.
• Keep focus on the page when someone dismisses a note, and let the content below glide up.

• A brief confirmation that isn't tied to one place on the page: use a Toast.
• A destructive action someone can take back: act at once and offer Undo Pill.
• A decision that must block the page: use an alert dialog in Dialog.
• A short status on a row or a card: use a Badge.

Dismissible

Pass onDismiss for a close button, and pair it with open so the alert collapses instead of vanishing. Put the gap above it in innerClassName so the gap closes with it.

const [open, setOpen] = useState(true);<Alert  open={open}  innerClassName="pt-3"  tone="neutral"  title="Invoices go to billing@northwind.com"  onDismiss={() => setOpen(false)}>  Add a second address in Settings → Billing contacts.</Alert>

From error to success

Keep one alert mounted and change its tone, title and role as the state changes. The tint cross-fades and the icon swaps in place.

<Alert  tone={paid ? "success" : "danger"}  role={paid ? "status" : "alert"}  title={paid ? "Payment received" : "Your October payment failed"}>  {paid ? "Visa ending 4242 was charged $249.00." : "Visa ending 4242 was declined by the bank."}</Alert>

Present on load

Use role="none" for an alert that is part of the page when it loads, so it isn't announced over everything else.

<Alert tone="warning" role="none" title="Card expires in 6 days">  Update it before Oct 24 to keep your Pro plan.</Alert>

Alert

• role="status" is a polite live region and role="alert" an assertive one; role="none" adds no role. Change the content of a mounted alert, as in the error-to-success example, so the update is announced.
• The tone's icon is decorative and hidden from screen readers, so the title must say what happened on its own.
• The Dismiss button is a 24px target named "Dismiss". Pressing it moves focus to the next focusable element among the alert's siblings (the previous one when nothing follows, the alert itself as a last resort) before it calls onDismiss, so focus never drops to the page body.
• While closing, the content is inert; once closed, it is hidden, so it leaves the tab order and the accessibility tree.

The alert springs open and closed on its own height with the smooth spring (no overshoot), so the content below glides. Opening, the content fades in over 200ms on the enter curve just after the height starts; closing, it fades out in 100ms on the exit curve. A close mid-open turns around from the current height. When the tone changes, the tint and icon colour cross-fade over 150ms on the standard curve, and the icon swaps with a 4px blur: the old one leaves 3px up in 100ms, the new one rises 4px on the snappy spring. The Dismiss button presses to 0.96. Reduced motion: the height snaps, and the content and icon fade in 100ms with no travel or blur.

Pick Alert for a message tied to a place on the page, and Toast for a passing confirmation. Choose tone by what happened and role by urgency: alert only for errors that need action now, none for alerts rendered with the page. For a dismissible alert, keep it mounted and drive open from state in onDismiss.

Don't conditionally render it to hide it ({show && <Alert />}); set open={false} so it collapses and the page glides. Don't put margin on the alert or a gap on its parent for spacing above a dismissible alert; use innerClassName. Don't wrap it in your own height animation or move focus in onDismiss: Alert already does both.

The title and description wrap in the space left beside the icon and the Dismiss button, and actions wrap onto new lines on a narrow screen.

• Toast: a passing message, not tied to a place on the page.
• Undo Pill: undo a reversible action instead of warning about it.
• Dialog: a blocking confirmation.