Balance Logo
Balance
Reckon Design System
Open playroom

Toast

The toast is a non-disruptive message that appears over the interface to provide at-a-glance feedback on the outcome of an action.
Install
pnpm add @balance-web/toast
Import usage
import {
ToastProvider,
useToasts
} from '@balance-web/toast';
  • Code
  • API

Use to provide general status messages that aren’t critical and require no action. For example, you might show a toast message to inform the user that their recent action was successful.

Setup

Unlike other Balance components, Toast is exposed via a hook and rendered automatically at the top-right of the viewport using a React portal. This is managed by the ToastProvider component. The useToast hook won't work unless it is nested within a ToastProvider. Most apps should just render this within their top level Core component.

NOTE: Only a render a single ToastProvider, not one per useToast instance.

import { Core } from '@balance-web/core';
import { ToastProvider } from '@balance-web/toast';
return (
<Core>
<ToastProvider>
<AppContent />
</ToastProvider>
</Core>
);

Usage

Toasts are a good way to communicate out-of-flow messages. You'll typically add a toast within a React effect when a form is submitted, but for these examples we're just going to add them via a button.

Hook

Access the addToast and removeToast methods with the useToasts hook.

The toast title should be short and affirmative.

Edit in Playroom

Message

Provide an optional message to give the user more information about the outcome of an action.

Preserve

By default, each toast will auto-dimiss after five seconds. Pass the preserve option to disable this behaviour, and keep the toast visible until the user intentionally dismisses it.

Reserve this behaviour for toasts that the user must see and acknowledge, like a server error or lost connection.

Tone

Toasts are available in four tones:

  • Use the informative (default) tone for general notifications.
  • The positive tone should be used to convey a successful action.
  • Use the warning tone to warn the user about some future event or action.
  • Reserve the critical tone for errors not caused by the user, like a connection issue.

Programmatic removal

You may want to remove a toast programmatically, when some state has changed outside of any user interaction. For instance, when they have lost or regained connectivity.

Provide a unique ID to the addToast options, which you can use later to remove the toast.

Copyright © 2024 Reckon. Designed and developed in partnership with Thinkmill.
Bitbucket logoJira software logoConfluence logo