Toast

ReactProps

Github Storybook Markdown Copy for LLM

Brief, non-blocking status messages queued in a fixed viewport region.

Toasts display brief, non-blocking status messages in a fixed region of the viewport. Messages are queued, stacked, and styled with MessageBlock.

Import

import { ToastRegion, toastQueue } from "@cfa/react-core";

Toast uses two exports:

• ToastRegion renders the toast stack in your application. Mount it once near the root of your app.
• toastQueue adds and closes toasts. Call toastQueue.add() from anywhere — for example, in a button handler or after an API request completes.

Live Editor

Live examples below use a shared ToastRegion mounted at the bottom right of the docs page.

Guidelines

When to use

• Toast is a brief acknowledgment of a completed action or outcome that does not interrupt the current task.

Do

• Keep it to one short sentence.
• Use variant for severity: info, success, warning, or error.
• Keep copy short. Say what happened and what to do next, if anything.
• Group all toasts in a single screen anchor, such as top-right or bottom-left.
• Recommend capping how many toasts are visible at once.
• Auto-dismiss info and success toasts. Keep warning and error visible until dismissed.
• When a toast includes an action, do not auto-dismiss while the action is available.
• Only include content that is safe to disappear.

Avoid

• Using Toast for blocking information people must acknowledge. Use Modal.
• Using Toast for persistent system or page-level status. Use BannerMessage.
• Using Toast for a message tied to a field, form, or section. Use MessageBlock.
• Putting information people may need again later.

Usage

function App() {
  return (
    <>
      <ToastRegion />
      {/* Your app routes */}
    </>
  );
}

function SaveButton() {
  return (
    <Button
      onPress={async () => {
        await saveChanges(); // your save handler
        toastQueue.add({
          severity: "success",
          title: "Saved",
          description: "Your changes were saved.",
        });
      }}
    >
      Save
    </Button>
  );
}

API

toastQueue

toastQueue is a shared queue for your application. Import it and call its methods directly.

import { toastQueue } from "@cfa/react-core";

Methods

• add(message, options?) - Adds a toast to the queue and returns its key.
• close(key) - Closes a specific toast by key.
• clear() - Removes all queued toasts.
• pauseAll() - Pauses auto-dismiss timers for visible toasts.
• resumeAll() - Resumes auto-dismiss timers for visible toasts.

const key = toastQueue.add(
  {
    severity: "success",
    title: "Saved",
    description: "Your changes were saved.",
  },
  { timeout: 5000, onClose: () => console.log("Toast closed") }
);

toastQueue.close(key);

add(message, options?)

message

The toast content to display.

• title (required) - The toast title.
• description (optional) - Optional supporting text.
• severity (optional) - Controls the icon and visual treatment. Defaults to "info". One of "info", "success", "warning", or "error".
• action (optional) - Optional action rendered below the description. The toast closes after the action runs.
  • label - The action label.
  • onPress - The action to run before the toast closes.
• iconOverride (optional) - Override the default severity icon.

options

Optional settings passed as the second argument to toastQueue.add().

• timeout (optional) - Time in milliseconds before the toast closes automatically. Omit to keep the toast visible until dismissed.
• onClose (optional) - Callback fired when the toast closes.

ToastRegion

ToastRegion is the render target for toastQueue. Mount it once in your app.

<ToastRegion placement="bottom right" />

See Props for the full list of ToastRegion props.

Behavior

• Mount only one ToastRegion in your application. Multiple regions connected to the shared toastQueue will render the same toast in each region.
• The queue shows up to three toasts at a time. Additional messages wait in the queue until a visible toast is dismissed.
• Toasts stay visible until dismissed by default. Pass timeout to toastQueue.add() to auto-dismiss after a delay.
• When a toast includes an action, the action runs first and the toast closes afterward.

Examples

Severity

The severity value controls the icon and visual treatment of each toast.

Dismissible and timed

Queued messages stay visible by default until the user closes them. Any severity can opt into auto-dismiss by passing a timeout to toastQueue.add().

Placement

Use the placement prop on ToastRegion to position the toast stack within the viewport. The default is "bottom right".

Supported values: "top left", "top center", "top right", "bottom left", "bottom center", and "bottom right".

<ToastRegion placement="top center" />

Stacking

Multiple messages added to the queue stack together. The shared queue controls how many toasts are visible at once.

Action

Add an optional action to a toast with message.action. The toast closes after the action runs.

Long content

Longer toast content wraps within the fixed toast width so the region remains usable on narrow screens and does not overflow the viewport.