# Toast

Headless, unstyled notifications stacked in a viewport. Add them with `Toast.useToastManager()`, or a `Toast.createToastManager()` instance outside React. They auto-dismiss on a timer that pauses while the viewport is hovered or focused, the window is blurred or the tab is hidden, queue beyond a limit, and announce themselves to screen readers. `F6` moves focus to the newest toast and back.

## Use for

- feedback for an action that has no surface of its own, such as a save after its form closed
- a loading, then success or error, notice for a promise
- a short confirmation beside the element that caused it, such as Copied
- showing a notification from outside React

## Practices

- Do: Render every toast from `useToastManager().toasts`, and filter anchored ones with `Toast.isAnchored` into a `Toast.Positioner`.
- Do: Hide `data-limited` toasts with CSS. They stay in the list, inert, while queued.
- Do: Use `manager.promise()` for an async action instead of adding and updating toasts by hand. It rethrows a rejection after showing the error toast, so catch it.
- Do: Pass the same `id` to `add` to refresh an open toast. It bumps `repeatCount` and sets `data-repeated`.
- Don't: Use a toast for something the user must answer. Use `Dialog`, or `useConfirmController` for a confirm step.
- Don't: Render `Toast.Arrow` outside `Toast.Positioner`. It throws.

## API reference

### Toast.Provider

Owns the toast list, timers and queue. Renders no element.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `timeout` | `number` | `5000` | Auto-dismiss delay in ms. `0` keeps toasts until closed. |
| `limit` | `number` | `3` | Most stacked toasts shown at once. Older ones beyond it are marked `limited`. |
| `toastManager` | `ExternalToastManager` |  | A manager from `createToastManager()`, for adding toasts outside React. |

### Toast.Portal

Portals its children.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `root` | `HTMLElement \| null \| RefObject<HTMLElement \| null>` | ``the `Portal` container`` | The element to portal into. |

### Toast.Viewport

A `div` with `role="region"` and `aria-label="Notifications"` that holds the stack. Hover or focus inside pauses every timer. Carries `data-expanded` and `--toast-frontmost-height`.

### Toast.Positioner

Places one toast against an anchor element, outside the stack and the limit. Carries `data-side`, `data-align`, `data-anchor-hidden` and the anchor CSS variables. Fields in `toast.positionerProps` override its props.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `toast` | `ToastObject` |  | The toast from `useToastManager().toasts`. |
| `anchor` | `Element \| null` | `null` | The element to sit next to. |
| `side` | `ToastSide` | `'top'` | The side of the anchor. Flips when there is no room. |
| `align` | `ToastAlign` | `'center'` | Alignment along that side. |
| `sideOffset` | `number` | `0` | Gap to the anchor in px. |
| `alignOffset` | `number` | `0` | Shift along the alignment axis in px. |

### Toast.Root

One toast: a focusable `div` with `role="dialog"`, labelled by its title and described by its description. `Escape` closes it. Carries `data-type`, `data-expanded`, `data-limited`, `data-repeated`, `data-starting-style` and `data-ending-style`, and `--toast-index`, `--toast-offset-y`, `--toast-height` and `--toast-frontmost-height`.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `toast` | `ToastObject` |  | The toast from `useToastManager().toasts`. |

### Toast.Arrow

A `FloatingArrow` `svg` pointing at the anchor, inside `Toast.Positioner`. Carries `data-side`.

### Toast.Content

A layout `div`. Carries `data-behind` on toasts behind the frontmost, and `data-expanded`.

### Toast.Title

An `h2` that labels the toast. Renders nothing without content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | `toast.title` | The title. |

### Toast.Description

A `p` that describes the toast. Renders nothing without content.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `React.ReactNode` | `toast.description` | The description. |

### Toast.Action

A `button` that merges `toast.actionProps`, runs its `onClick`, then closes the toast. Renders nothing without action props, children or `render`.

### Toast.Close

A `button` that closes the toast.

## Examples

### Stacked toasts

```tsx
function ToastList() {
  const { toasts } = Toast.useToastManager();
  return toasts.map(toast => (
    <Toast.Root key={toast.id} toast={toast}>
      <Toast.Content>
        <Toast.Title />
        <Toast.Description />
      </Toast.Content>
      <Toast.Action />
      <Toast.Close aria-label='Close' />
    </Toast.Root>
  ));
}

<Toast.Provider>
  <App />
  <Toast.Portal>
    <Toast.Viewport>
      <ToastList />
    </Toast.Viewport>
  </Toast.Portal>
</Toast.Provider>
```

### Promise

```tsx
const manager = Toast.useToastManager();
manager
  .promise(saveProfile(), {
    loading: 'Saving…',
    success: 'Profile saved',
    error: 'Could not save',
  })
  .catch(() => {});
```

## Related

- [Portal](/docs/primitives/portal.md)
- [Dialog](/docs/components/dialog.md)
