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.

Installation

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.

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.

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

{
  "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

[
  {
    "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.