Toast

A Toast is a small, temporary notification that appears on the screen to inform users about the outcome of an action or to provide brief feedback. Toasts are commonly used in applications to deliver messages such as success notifications, error alerts, or informational updates without interrupting the user's workflow.

Anatomy

A toast consists of a status icon, a title, an optional description, and a close button. It is placed in a region that stacks multiple toasts and keeps them above the rest of the interface.

• Icon: Signals the nature of the notification through its color.
• Close button: Dismisses the toast before it times out.

Appearance

The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.

Each variant uses a distinct icon color to signal the nature of the notification.

Usage

The <ToastProvider> Component should be in the root of your application, so it can be used anywhere in your app. You can use the addToast function to add a Toast to the Toaster. The Toast will appear at the bottom right of the screen by default. With the position prop you can change the position of all Toasts.

Simple toast

A Toast should be used when you want to give users quick, non-intrusive feedback after an action, such as saving, deleting, or uploading data. It appears on the edge of the screen. Because it doesn't interrupt the user's workflow, a Toast is ideal for success messages, notifications, or error alerts that don't need immediate interaction. The message should be clear, concise, and easy to read.

Default timeouts

addToast picks a timeout based on variant when you don't pass one. Low-severity, reassuring toasts auto-dismiss, while higher-severity or actionable ones stay until the user dismisses them.

To override the default, pass timeout. An explicit value is honored and clamped up to the 5000ms minimum, and timeout: 0 keeps any toast on screen until it is dismissed.

Auto dismiss

Set timeout (in milliseconds) to override the per-variant default and dismiss a Toast after a specific duration. This is useful to make a warning or error clear on its own, or to extend a success toast. Values below the 5000ms minimum are clamped up.

Programmatic dismiss

addToast does return the key of the Toast, with this the Toast can be dismissed programmatically, by saving the key of the Toast and then using removeToast.

Close all toasts

All Toasts can be dismissed with clearToasts.

Committing work when a Toast closes

Pass onClose to run something at the moment the Toast goes away, whichever way it goes: its timeout ran out, the user pressed the close button, removeToast closed it, or clearToasts emptied the queue.

Offering undo

addUndoToast reports a destructive action as done, gives the user a window to take it back, and sends the real request only if they don't. Hide the effect yourself, restore it in onUndo, and send the request from onCommit.

const { addUndoToast } = useToast();

const deleteList = (list: MailingList) => {
  setPending(current => [...current, list.id]);

  addUndoToast({
    title: `“${list.name}” deleted`,
    onUndo: () => restore(list.id),
    onCommit: () => deleteRequest(list.id),
  });
};

onCommit runs when the window closes without an undo, whichever way the Toast went away. The undo button is named after the title, so stacked undo Toasts do not all announce a bare "Undo": name what happened to what and this takes care of itself.

An undo Toast carries no close button and ignores timeout: 0. Destructive Actions explains why, and when to offer undo at all rather than a confirmation dialog.

Action

Toasts can also include an action element, which is typically a button or link that allows the user to take a specific action related to the toast message. This is useful for scenarios where you want to provide users with a way to respond to the notification.

To add an action element, use the action prop which accepts any React component (button, link, etc.).

Props

Toast Provider

Toast options

Options accepted by addToast.

Undo Toast options

Options accepted by addUndoToast.