skip to content
menu
patterns · message handling
patternsfeedback & status

message handling

Our apps have a lot to tell people: that something worked, that something failed, that part of a list is missing, that a field needs a fix. If every message appeared in the same spot, in the same way, people would soon stop reading them. So each message goes to the one place that fits what it is about, and stays there for as long as it is true.

missingneeds attentionmissingmissingmissingmissingfiftyUse a number8 episodes queued1234
Four places for a message, each for its own kind of news.
  1. A banner sits above the content and talks about the page as a whole: “105 titles can't be checked”. It stays until that stops being true.
  2. A status belongs to one item, in its row or on its page: “needs attention”. It stays as long as the item is in that state.
  3. A field's error belongs to one value in a form: “Use a number”. It stays until the value is fixed.
  4. A toast confirms something people just did: “8 episodes queued”. It disappears after a few seconds.

Each of these is a real component, with its own page where it can be tried live: the banner, the status, the field and the toast.

which one

the message is about it lasts use for example
Something about the content of the page Until it changes A banner: information, warning or error “105 titles can't be checked: the catalog holds them without an identity.”
A refresh that failed, with older content still on the screen Until it works again A warning banner that says how old the content is, with “try again” “Couldn't refresh the list; it shows what was loaded 4 minutes ago.”
A load that failed, with nothing to show Until it works again An error message in place of the list, with “try again”; see empty states “couldn't load the list”
Something people just did, that worked A few seconds A toast, without buttons in it “8 episodes queued · 2 skipped: held already or under way”
Something people did, that failed Until it is dismissed or tried again An error banner that can be dismissed, with the technical error under details “Couldn't queue the grab.”
One item's state As long as it is true The item's status “needs attention”
One value in a form Until it is fixed The field's error “Use a number”
Technical details behind any of these When asked for Under “details”, in the banner or in the row “http 502 bad gateway”
A decision before going on Until it is answered A dialog, for the decision rather than the message “delete volume”
Work under way Until it is done A loader, or a progress value; see loading and progress “62% · 1.4 of 2.2 gb”

a few rules

  • Say it once. An error is a banner or a toast, not both, and a row's status isn't repeated in a banner.
  • One or two banners at most. A third usually means the screen has a problem to fix, not a message to add.
  • Toasts are for good news and progress. Not for an error people have to act on, because it would be gone before they read it, and without a button in it.
  • Errors say what failed, and how to go on: “Couldn't load the list.”, with “try again”. The technical error goes under details.
  • Keep what is known. When a refresh fails, keep showing the last data, and say how old it is.
  • No ids, codes or raw errors in the message itself. They go under details, one click away.
Couldn't refresh the list; it shows whatwas loaded 4 minutes ago.try againmissingmissingmissingmissing
A refresh that failed: the rows from before stay, and the banner says how old they are and offers to try again.
do
Couldn't queue the grab.details ▸
A failed action: an error banner that stays, with the technical text one click away.
don't
Error 503: serviceunavailable
An error in a toast: gone before it is read, and nothing to act on.
do
8 episodes queued
A toast for the result of an action, in counts. It leaves on its own.
don't
Success! Your grab request was submitted…
A banner that stays forever for something that happened once.

how they behave

  • A banner stays until its condition changes. The screen remembers when someone dismissed it, and brings it back when the condition changes again, such as a new count or a new failure.
  • A toast leaves after five seconds. It waits while the pointer rests on it, and no more than three show at once.
  • Error banners are read out the moment they appear; other banners are read out when the screen reader has finished what it was saying.
  • The focus never jumps to a message. After a failed save, it moves to the first field that needs a fix instead; see forms and settings.

the words

  • A banner. One or two sentences, in sentence case: what is true, and what it means for this screen. Its buttons are verbs: “show them”, “ask the catalog again”, “try again”.
  • A toast. What happened, in counts: “8 episodes queued”. No “successfully”, and no full stop needed.
  • An error. “Couldn't …” and the thing, then the way forward. No blame, and no “oops”.