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

const { addToast } = useToasts();
const handleClick = () => {
  addToast({ title: 'Basic toast' });
};
return <ActionButton onClick={handleClick} label="Show basic toast" />;

Message

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

Edit in Playroom

const { addToast } = useToasts();
const handleClick = () => {
  addToast({
    title: 'Something happened',
    message: 'Some details about what has happened',
  });
};
return <ActionButton onClick={handleClick} label="Show toast with message" />;

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.

Edit in Playroom

const { addToast } = useToasts();
const handleClick = () => {
  addToast({
    title: 'Important notice',
    preserve: true,
    message: 'This toast will stay visible until dismissed by the user.',
  });
};
return <ActionButton onClick={handleClick} label="Show preserved toast" />;

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.

Edit in Playroom

const { addToast, removeToast } = useToasts();
const toastId = 'unique-toast-id';
const add = () => {
  addToast({
    id: toastId,
    preserve: true,
    title: 'Removable toast',
    message: 'The content of the toast message.',
  });
};
const remove = () => {
  removeToast(toastId);
};
return (
  <Inline gap="small">
    <ActionButton onClick={add} label="Add toast" />
    <ActionButton onClick={remove} label="Remove toast" />
  </Inline>
);