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

## Import

```jsx
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.

```jsx
function ToastExample() {
  return (
    <Button
      onPress={() => {
        toastQueue.add({
          severity: "info",
          title: "Toast title",
          description: "This queued message is rendered with MessageBlock styling.",
        });
      }}
    >
      Show toast
    </Button>
  );
}
```

## 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

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
<ToastRegion placement="bottom right" />
```

See [Props](/components/toast/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.

```jsx
function SeverityExample() {
  const severities = ["info", "success", "warning", "error"];

  return (
    <div style={{ display: "flex", flexWrap: "wrap", gap: 12 }}>
      {severities.map((severity) => (
        <Button
          key={severity}
          size="md"
          onPress={() => {
            toastQueue.add({
              severity,
              title: `${severity.charAt(0).toUpperCase()}${severity.slice(1)} toast`,
              description: "This queued MessageBlock stays visible until it is dismissed.",
            });
          }}
        >
          Show {severity}
        </Button>
      ))}
    </div>
  );
}
```

### 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()`.

```jsx
function DismissibleAndTimedExample() {
  return (
    <div style={{ display: "flex", flexWrap: "wrap", gap: 12 }}>
      <Button
        size="md"
        onPress={() => {
          toastQueue.add({
            severity: "warning",
            title: "Dismissible warning",
            description: "Queued messages stay visible by default until the user closes them.",
          });
        }}
      >
        Show dismissible warning
      </Button>
      <Button
        size="md"
        onPress={() => {
          toastQueue.add(
            {
              severity: "warning",
              title: "Timed warning",
              description: "Consumers can opt any severity into auto-dismiss with a timeout.",
            },
            { timeout: 5000 }
          );
        }}
      >
        Show timed warning
      </Button>
    </div>
  );
}
```

### 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"`.

```jsx
<ToastRegion placement="top center" />
```

### Stacking

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

```jsx
function StackingExample() {
  const severities = ["info", "success", "warning"];

  return (
    <Button
      size="md"
      onPress={() => {
        severities.forEach((severity, index) => {
          toastQueue.add({
            severity,
            title: `Queued toast ${index + 1}`,
            description: "The shared queue controls how many toasts are visible.",
          });
        });
      }}
    >
      Add three toasts
    </Button>
  );
}
```

### Action

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

```jsx
function ActionExample() {
  return (
    <Button
      size="md"
      onPress={() => {
        toastQueue.add({
          severity: "info",
          title: "File archived",
          description: "The action closes this toast after it runs.",
          action: {
            label: "UNDO",
            onPress: () => {
              alert("Undo pressed");
            },
          },
        });
      }}
    >
      Show action toast
    </Button>
  );
}
```

### 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.

```jsx
function LongContentExample() {
  return (
    <Button
      size="md"
      onPress={() => {
        toastQueue.add({
          severity: "error",
          title: "The upload could not be completed because the file name is unusually long",
          description:
            "Longer toast content wraps within the fixed toast width so the region remains usable on narrow screens and does not overflow the viewport.",
        });
      }}
    >
      Show long content
    </Button>
  );
}
```

## Props

### ToastRegion

| Name | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| className | `string` | - | CSS class applied to the toast region. |
| placement | `ToastPlacement` | `bottom right` | Where the toast region is positioned. |
| style | `CSSProperties` | - | Inline styles applied to the toast region. |