BRAID
Braid Logo
 

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 after 10 seconds.Translation hint The aria-label for the close button can be customised by providing a closeLabel prop.
Open in Playroom

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.
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.
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.