Toaster

Toaster creates temporary, floating messages in the edges of the screen that communicate information to the user.

For persistent messaging, contextual or specific to a particular part of an application, consider Notification component.

Import#

import {
  createToastManager,
  Toaster,
  useToastManager
} from '@volue/wave-react';

createToastManager: Factory to create a toastManager.
Toaster: The wrapper component that provides toastManager for its children.
useToastManager: The hook to consume toastManager in your React components.
toastManager can also be used to create toasts from outside of your React components.

Provide toast manager#

Add <Toaster> high up in your app's tree, preferably in the root component.

import { Toaster, createToastManager } from '@volue/wave-react';

// `toastManager` instance can be created outside of your React component
const toastManager = createToastManager();

// provide `toastManager` in your root App component
function App() {
  return (
    <SomeGlobalProvider>
      <Toaster manager={toastManager}>
        <AppLayout>{children}</AppLayout>
      </Toaster>
    </SomeGlobalProvider>
  );
}

Toast manager API#

toastManager provides two methods:

toastManager.addToast(toastDefinition); // returns disposer
toastManager.removeToast(toastId);

addToast() returns a toast disposer function.

If you create toasts within React.useEffect() and the component becomes unmounted, the toasts will be automatically dismissed.

Toast definition#

Prop	Type	Default
`message`*	`ValueOrFunction<Renderable, string>`	No default value
`type`	`enum`	`"info"`
`duration`	`number \| null`	`5000`
`isClosable`	`boolean`	`false`
`action`	`{ label: string; onAction: (toastId: string) => void }`	No default value
`id`	`string`	No default value
`className`	`string`	No default value
`css`	`StitchesCss`	No default value

Examples#

Toast types#

Toasts are used to provide relevant feedback to the user, typically after they've taken an action. They can convey a warning, error, success, or info message.

Toasts should be used for brief and direct communication. Only include the highest priority information and aim for no more than ~100 characters.

Auto-close timer will pause when you hover on a toast.

You can disable this behavior by setting shouldPauseOnHover to false on Toaster.

You can prevent essential toasts from disappearing automatically, by setting duration prop to null.

Toaster position#

You can change the position of all toasts by supplying position prop.

Size#

You can change the size of all toasts by supplying size prop. Toasts come in two sizes: medium (default) and small.

Action#

You can allow users to perform a single associated action via the action prop.

Do not include actions such as “Cancel”, for dismissing toast. The dismiss button is already included in the component.

An actionable notification should persist until user dismisses it or have a time-out of at least 10 seconds, allowing users time to interact with it.

Limit number of toasts#

By default Toaster will show at most 5 latest toasts.

You can change this limit by supplying limit prop. Setting limit to null will result in no limit.

API Reference#

Prop	Type	Default
`manager`*	`ToastManager`	No default value
`position`	`enum`	`"topRight"`
`size`	`enum`	`"medium"`
`limit`	`number \| null`	`5`
`shouldPauseOnHover`	`boolean`	`true`
`css`	`StitchesCss`	No default value

Guidelines#

Notifications should inform users about any updates or changes to the application.

Toasts provide limited space for content, and therefore the content must be short and concise, providing immediate feedback in response to a user action or informing users of a process that the app has performed or will perform.

Toasts are usually time-based but can also be shown until the user decides to dismiss them manually.

Toast notifications serve as an essential part of visual feedback, yet, they can't be overused since this may annoy the user.