# Toast

- Page: https://jiguang132.com/resources/astryx/docs/toast
- Resource: Astryx (https://jiguang132.com/resources/astryx.md)
- All guides: https://jiguang132.com/resources/astryx/docs.md

Toast shows a brief, non-blocking notification to confirm an action or present temporary information. Use it for scenarios where the user needs feedback but not a decision, such as saving, deleting, or changing a status.

For production use, prefer the `useToast()` hook; it handles positioning, stacking, auto-dismiss, and deduplication via `ToastViewport`. Toasts stay within viewport and safe-area gutters, wrap long message content, and enter, exit, or swipe-dismiss toward their configured top or bottom edge. The vertical swipe uses the same spatial model as placement motion: top Toasts leave upward and bottom Toasts leave downward. Swipe waits for dominant edge-directed intent before cancelling native touch movement and reports the existing manual dismissal reason. Pen is supported as direct-contact input; mouse drag is excluded to avoid conflicting with desktop text selection, where the visible close control remains available. Set `isAutoHide: false` explicitly when an action or message must remain available. The `Toast` component renders the visual toast element inline and is useful for previews, documentation, and static showcases where the viewport lifecycle is not needed.

## Installation

```bash
npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0
```

Requires React 19+, base CSS and a Theme provider. See [Setup](/resources/astryx/docs/getting-started).

## Toast

Toast shows a brief, non-blocking notification to confirm an action or present temporary information. Use it for scenarios where the user needs feedback but not a decision, such as saving, deleting, or changing a status.

For production use, prefer the `useToast()` hook; it handles positioning, stacking, auto-dismiss, and deduplication via `ToastViewport`. Toasts stay within viewport and safe-area gutters, wrap long message content, and enter, exit, or swipe-dismiss toward their configured top or bottom edge. The vertical swipe uses the same spatial model as placement motion: top Toasts leave upward and bottom Toasts leave downward. Swipe waits for dominant edge-directed intent before cancelling native touch movement and reports the existing manual dismissal reason. Pen is supported as direct-contact input; mouse drag is excluded to avoid conflicting with desktop text selection, where the visible close control remains available. Set `isAutoHide: false` explicitly when an action or message must remain available. The `Toast` component renders the visual toast element inline and is useful for previews, documentation, and static showcases where the viewport lifecycle is not needed.

| Prop | Type | Default | Description |
|---|---|---|---|
| body * | ReactNode |  | Primary message content. |
| type | 'info' \| 'error' | 'info' | Toast type controlling background color. Error toasts persist until dismissed. |
| isAutoHide | boolean |  | Whether the toast auto-dismisses. Defaults to true for info, false for error. |
| autoHideDuration | number | 5000 | Duration in ms before auto-dismiss. Timed content must satisfy WCAG 2.2.1. |
| endContent | ReactNode |  | Content rendered at the trailing end (e.g. Undo button, link). Keep action labels short. |
| uniqueID | string |  | Unique identifier for deduplication. |
| collisionBehavior | 'overwrite' \| 'ignore' | 'overwrite' | Behavior when a toast with matching uniqueID already exists. |
| onHide | (reason: "auto" \| "manual") => void |  | Callback fired when the toast is removed. |
| onDismiss * | (reason: "auto" \| "manual") => void |  | Callback fired when the toast is dismissed. |
| renderContent | (toast: ToastContentRenderProps) => ReactNode |  | Replaces the content of this toast's card with your own layout. Astryx keeps the card, its astryx-toast theme target, the live-region role and auto-hide behavior, then hands the renderer the message, endContent, resolved toast settings and a dismiss callback. The custom renderer owns every control in its layout: compose the control you want and call dismiss from it. Astryx does not inject a fallback close into custom content. Per-toast: an app shares one layout by wrapping useToast and passing it on every call, while a toast raised by library code that never passes it renders as an ordinary Astryx toast. The argument is {body, endContent, type, isAutoHide, autoHideDuration, dismiss}, where type is 'info' \| 'error'. |

### Usage guidance

- Keep messages short: only a few words that tell the user what happened, like "Changes saved" or "Message sent".
- Add a short undo action in the endContent slot for reversible operations. Set isAutoHide to false when the action must remain available.
- Use uniqueID to deduplicate toasts that fire from repeated actions, like clicking a save button multiple times.
- Use error type for failures that need attention but not immediate action; it persists until dismissed so the user won't miss it.
- Avoid: Don't use a toast for critical errors that block the user. Use Banner for persistent, in-context messaging that requires acknowledgment.
- Avoid: Don't put long or multi-line content in a toast; it disappears after 5 seconds and the user may not finish reading.
- Avoid: Don't show form validation errors as toasts. Use inline field validation so the user can see exactly which field needs fixing.

### Theming API

```json
{
  "targets": [
    {
      "className": "astryx-toast",
      "visualProps": [
        "type"
      ]
    }
  ],
  "vars": [
    {
      "name": "--_toast-slide-y",
      "description": "Private block-axis offset inherited from ToastViewport for entry and exit motion",
      "default": "var(--spacing-2)",
      "private": true
    },
    {
      "name": "--_toast-swipe-y",
      "description": "Private active swipe offset along the block axis",
      "default": "0px",
      "private": true
    },
    {
      "name": "--_toast-swipe-exit-y",
      "description": "Private completed-swipe exit offset",
      "default": "var(--_toast-swipe-y)",
      "private": true
    },
    {
      "name": "--_toast-swipe-opacity",
      "description": "Private opacity feedback during an accepted swipe",
      "default": "1",
      "private": true
    },
    {
      "name": "--_toast-swipe-scale",
      "description": "Private scale feedback during an accepted swipe",
      "default": "1",
      "private": true
    }
  ]
}
```

### Anatomy

- **Body**: The primary message text describing what happened or what the user should know.
- **End content**: A trailing action like an Undo button or a link, placed after the body text.
- **Dismiss button**: A close button that lets the user manually dismiss the toast before auto-hide.

## useToast

Hook for showing toast notifications from anywhere in your component tree. Returns a function that accepts toast options and shows the notification. Works automatically with LayerProvider or self-mounts a fallback viewport.

### Returns

```json
[
  {
    "name": "showToast",
    "type": "(options: ToastOptions) => () => void",
    "description": "Show a toast notification. Returns a dismiss function. Options include body (ReactNode), type (\"info\" | \"error\"), isAutoHide, autoHideDuration, endContent, uniqueID, and collisionBehavior."
  }
]
```

### Usage guidance

- Use for transient success/error feedback that does not require user action.
- Set uniqueID to deduplicate toasts from rapid user actions.
- Avoid: Use for critical errors that require acknowledgment; use AlertDialog instead.
- Avoid: Call useToast in the same component that renders LayerProvider; it must be called from a child component inside the provider.


## Examples

- Toast: Imperative toast notifications triggered with useToast and rendered in the toast viewport.
- Toast — Action: Persistent toasts with a trailing button or link so the user can act on the notification, like undoing a delete or viewing a report.
- Toast — Deduplication: Prevent duplicate toasts with uniqueID. Use ignore to keep the first toast, or overwrite to replace it with updated content like a progress percentage.
- Toast — Dismiss: Show a persistent toast and dismiss it programmatically using the function returned by useToast. Use for long-running operations that need manual cleanup.
- Toast — Stacking: Multiple toasts stacking vertically with smooth enter and exit animations. Click repeatedly to see how toasts queue and dismiss.
- Toast — Types: Info and error toast variants side by side. Info toasts auto-dismiss after 5 seconds, error toasts persist until the user dismisses them.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt