BRAID
Braid Design System
GuidesFoundationsComponentsPatternsStyles

useToast

A brief, temporary message that appears at the bottom of the screen to acknowledge user actions without interrupting their workflow.
 
Open in Playroom

Accessibility

Follows the WAI-ARIA Alert Pattern.

Choosing a tone

Use the tone property to help communicate the meaning behind your message. Toasts support positive, critical and neutral tones.Read more about Tones.
 
Open in Playroom

Descriptions

If you need to provide more context to the user, you can also provide a description.
 
Open in Playroom

Including actions

You can allow users to perform a single associated action via the action prop. When the action is performed, the toast is automatically removed from the screen.
 
Open in Playroom
When an action is provided in addition to a description, the layout will stack vertically to better accommodate all the content.
 
Open in Playroom

Dismissing messages

A toast message can be dismissed via the close button, or automatically based on the duration property. The default duration is standard (10 seconds), or can be optionally set to either short (6 seconds) or indefinite which remains on screen until dismissed.Regardless of duration, a toast will not auto-dismiss while it has hover or keyboard focus. This ensures a user actively reading or interacting with a toast is never cut off mid-way.Translation hint The aria-label for the close button can be customised by providing a closeLabel prop.
 
Open in Playroom

Choosing a duration

Standard is set as a sensible default for most use cases.You may however decide to use short or indefinite in specific cases.
Use short if your message:
  • is a simple confirmation the user doesn’t need to act on
  • reads comfortably as a short phrase, roughly 10-12 words or fewer
  • is reflected elsewhere in the UI, so nothing is lost if it’s missed
Use indefinite if your message:
  • is an error or warning the user needs to resolve
  • is the only place the user can access this information
  • has an action important enough that it shouldn’t risk timing out before it’s noticed
For almost all uses, standard is the recommended duration. If unsure whether to use short or standard, prefer standard. A toast that outstays its welcome is a smaller problem than one that disappears before a user has had a chance to read it.

Deduping

You can assign a key to each toast which is used to guarantee that only a single toast with a given key is visible at once. This is particularly useful for reducing visual noise when your application has the potential to generate a lot of toasts.
 
Open in Playroom

Playroom prototyping

The showToast function used in these examples is automatically available in Playroom. You do not need to call the useToast function.

Development considerations

To get access to the showToast function in your application code, call the useToast Hook.
Open in Playroom
import { useToast } from 'braid-design-system';

export const Demo = () => {
  const showToast = useToast();

  // etc...
}
To enable this Hook, wrap your app in a ToastProvider—typically where you render BraidProvider.
Open in Playroom
import { BraidProvider, ToastProvider } from 'braid-design-system';

export const App = () => (
  <BraidProvider>
    <ToastProvider>
      {/* App code... */}
    </ToastProvider>
  </BraidProvider>
)

When to use

Use a Toast if your message:
  • has been triggered by a user action relevant to their current task
  • does not impact the user’s ability to continue.
Don’t use a Toast if your message:
  • needs to be permanently on the screen (use plain Text instead)
  • impacts the user’s ability to continue (use an Alert or Notice instead)
  • doesn’t relate to the user’s current task (as this may cause a distraction).

Alternatives

  • Alert — For strong in-flow messages that sit at page or section level.
  • Notice — For light in-flow messages that sit within a section, card, or widget.
On this page