Feedback
Toast, Banner, Callout, field errors, Alert Dialog and Empty, sorted by how urgent the message is, how long it stays and how much of the app it speaks for.
Feedback answers one of three questions: did that work, is something wrong, and what now. The component you pick decides how loudly you answer, how long the answer stays and how much of the screen it claims. Get those three right and the wording gets much easier.
Decision table
| Component | Urgency | How long it stays | Scope | Interrupts |
|---|---|---|---|---|
| Toast | Low. The result of an action | 5 seconds, 10 with an action | The thing the reader just did | Only errors and warnings, read out right away |
| Field error | Medium. Blocks submitting | Until the input is fixed | One field | No |
| Form error summary | Medium. Several problems | Until the fields are fixed | One form | Moves focus once |
| Callout | Low. Context worth reading | Always, it is part of the content | One section | No |
| Banner | Medium to high | Until the state ends or it is dismissed | The whole app or page | No, unless role="alert" |
| Alert Dialog | High. Needs a decision | Until answered | The task at hand | Yes, it is modal |
| Empty | None. Nothing is wrong | While there is nothing to show | A list, a table, a panel | No |
Two quick tests sort most cases. If the message is about something the reader typed, it goes next to what they typed. If it is still true after they leave the page, it does not belong in a toast.
Toast
A Toast confirms something the reader just did and gets out of the way. "Invitation sent", "Changes saved", "3 conversations archived". It is read out through a live region, the timer pauses on hover and focus, and with an action it stays up for 10 seconds instead of 5.
That still means it disappears. Anything the reader has to act on, or might want to read twice, needs a home that stays.
3 conversations archived
Find them in Archive whenever you need them.
UndoProject deleted
acme-web and its 14 deployments are gone.
Undo- One toast per action. Three toasts for one click is noise, and
maxToastswill start dropping them anyway. - Do not toast what the screen already shows. If the new row appears in the table, "Row added" says nothing new.
- Errors in toasts are for failures the reader cannot fix in place, like a network error after saving. Say what failed and what to try next.
Errors from a form
Validation errors go next to the field that caused them, through
Field.Error. That is where the reader is looking, it stays until they fix it, and the field's aria-describedby points at it so screen readers read it with the label.We send the invoice here.
Enter an email like ana@northwind.dev.
Invalid email
On long forms, add
Form.ErrorSummary at the top. After a failed submit it lists every problem as a link to its field and focus moves to the first invalid one. The details are in Forms.Banner and Callout
A Banner speaks for the whole app or the whole page: a trial that ends in three days, a workspace in read-only mode, an outage, a billing problem. It stays until the state changes or the reader dismisses it. Put it at the top, above the layout, and keep one at a time.
A Callout speaks for one section. It sits inside the content, next to what it explains, and it is not dismissible because it is part of the page.
Your workspace is read only until 14:00 UTC
We are moving it to a new region. Nothing is lost, and editing comes back on its own.
Tip
Drag the column headers of this table to reorder them.
The local version of that message is a Callout, placed right above the table:
Rotating the key signs everyone out
Active sessions end within a minute. Schedule it outside working hours.
Banners default to
role="region", which screen readers list but do not announce. Use role="alert" only when you inject a banner because something urgent just happened, since it interrupts whatever the reader is doing.Alert Dialog
The loudest option. It blocks the page and waits for an answer. Use it when the reader is about to lose something they cannot get back, and for nothing else. The full reasoning is in Overlays.
Empty
An Empty state is feedback too: it tells the reader the area works and is simply empty, and it tells them what to do about it. Every empty state needs a next step. On a first visit that is the action that fills it. After a search with no results, it is a way to clear or change the search.
No invoices yet
Invoices show up here after your first payment. Add a card to start the plan.
No data
Loading is not empty. Show a skeleton or a spinner while data is on its way, and only show the empty state once you know there is nothing.
Found something to improve?
Notice a bug, typo, or missing detail on this page? Help us make the documentation better by opening a GitHub issue.