Alert
NewAn inline message inside a page, card or dialog: something the merchant should know about the thing in front of them, in plain words on its tone's pale wash. Not a toast: it stays beside the problem until the problem goes.
Playground
Change the props. Turn on dismissible and press the cross to watch it leave.
Weights missing
<Alert
tone="warning"
title="Weights missing"
actions={<Button size="sm">Review products</Button>}
>
3 products are missing a weight, so shipping cannot be calculated.
</Alert>Tones
The tone is the meaning. Each one has its own icon and wash, and the words stay ink on all of them, so the message reads first and the colour backs it up. info is the default.
What each tone means
| Tone | Means | For example | Announced |
|---|---|---|---|
neutral | Context with no judgement: a note or a tip. | Prices include VAT | Politely |
info | Worth knowing, nothing to do yet. | Test mode, a new feature | Politely |
success | Done and good, and it stays true. | Stripe connected, domain verified | Politely |
warning | Needs the merchant soon, or something will go wrong. | Missing weights, low stock | At once |
critical | Something failed or is blocked. | Payment failed, payouts paused | At once |
With a title
Add a title when the message runs past a sentence or two. The title says what happened in a few words; under it the message steps back to slate and explains.
Payouts are paused
Actions
actions takes one or two small buttons (size="sm"): the move that fixes it, and perhaps a ghost button for a second, quieter one. They sit under the message. Press Try again.
Dismissing
dismissible adds a cross. Pressed, the alert fades, the space it leaves closes up so the content below glides into place, and it removes itself. onDismiss runs once it has gone: use it to remember the choice. Passing onDismiss on its own also shows the cross.
Only let merchants dismiss what they can safely ignore, such as news about a feature. A problem that is still there should stay until it is fixed.
Schedule discounts ahead
Customers enter this at checkout.
In a card and a dialog
An alert sits at the top of what it is about: the card, the form or the dialog. It is a block that fills the width it is given and brings no margins, so the container spaces it.
Shipping
How orders reach your customers.
Used when a product has no package of its own.
Long content
The message can hold paragraphs and a list, and the actions wrap onto a second line when the alert is narrow. Keep lists short: the alert says what is wrong, the page it links to holds the detail.
4 products could not be imported
The other 112 products from catalogue-autumn.csv are in your store. Fix these rows, then import the file again:
- Row 14, Oak standing desk: the price is empty.
- Row 27, Arden ergonomic chair (grey): the SKU ARD-CHR-BLK is already used.
- Row 51, Walnut monitor riser: the weight is not a number.
- Row 88, Cable tray: the image link could not be opened.
A title on its own
When the title says it all, leave out the message.
Your domain harbourdesk.co.uk is connected
Icon
Each tone brings its own Phosphor icon, drawn duotone so it reads as a tinted mark on the wash. Pass icon to use a picture that says more, coloured by the tone, or icon={null} to leave it out.
In both themes
Every tone, light and dark side by side. In dark the washes are the tone at 14% over the surface, the icons lift, and a hairline in the tone keeps each box crisp. The title holds at least 12:1 and the message at least 6.4:1 on every wash.
Payouts are paused
Payouts are paused
Guidelines
- One alert per area, at the top of what it is about. Several problems with one thing go in one alert, as a short list.
- Lead with what happened, then what it means or what to do. Sentence case, no exclamation marks, no "Error:" prefix: the tone and the icon already say it.
- Small buttons only: the action that fixes it, and perhaps a ghost button. Never a primary pill; the page already has its one.
- Dismissible only when ignoring it is safe. An alert about a problem goes away when the problem does.
Alert or something else
| The merchant needs | Use |
|---|---|
| To know about a lasting condition of this page, card or dialog | Alert |
| Feedback on what they just did ("Product saved") | A toast |
| To fix one field | The field's error |
| A status in a row or a header ("Unfulfilled") | Badge |
| To decide before going on | ConfirmDialog |
| To know there is nothing here yet | Empty state |
Accessibility
- Warnings and critical alerts are
role="alert", so a screen reader announces them as soon as they appear. The other tones arerole="status"and wait their turn. Passroleto change it, orrole="none"for a note that should only be read in place. - An alert that is already on the page when it loads is read in place, not announced.
- The icon is hidden from assistive tech. The words carry the meaning, so colour is never the only signal.
- The cross is a real button named "Dismiss" (
dismissLabeltranslates it). When the alert has gone, focus moves on to the next control instead of falling back to the top of the page. - Text holds at least 6.4:1 on every wash in both themes, and the icons at least 4.5:1.
- Under reduced motion it fades in and out without moving, and the space it leaves closes at once.
Props
Also accepts every native div attribute.
| Prop | Type | Default | Description |
|---|---|---|---|
tone | 'neutral' | 'info' | 'success' | 'warning' | 'critical' | 'info' | What the message means. Sets the icon, the wash and how it is announced. |
title | ReactNode | None | A short bold first line. |
titleAs | 'h2' | 'h3' | 'h4' | 'p' | 'div' | 'p' | Element for the title. |
children | ReactNode | None | The message. Text, or paragraphs and a short list. |
icon | ReactNode | None | Replaces the tone's icon. null hides it. |
actions | ReactNode | None | One or two small buttons under the message. |
dismissible | boolean | false | Shows the cross. The alert removes itself when it is pressed. |
onDismiss | () => void | None | Runs once a dismissed alert has gone. Shows the cross on its own too. |
dismissLabel | string | 'Dismiss' | Accessible name of the cross. |
role | string | None | Defaults to 'alert' for warning and critical, 'status' for the rest. |