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.
Preview loads on approachPreview loads on approach
Exact source · toast-showcase
// Copyright (c) Meta Platforms, Inc. and affiliates.
'use client';
// In production, use useToast() hook for proper positioning, stacking, and lifecycle.
import {Toast} from '@astryxdesign/core/Toast';
import {useToast} from '@astryxdesign/core/Toast';
import {Button} from '@astryxdesign/core/Button';
export default function ToastShowcase() {
const toast = useToast();
return (
<Toast
type="info"
body="Document saved successfully"
endContent={
<Button
label="Show toast"
variant="ghost"
size="sm"
onClick={() => toast({body: 'Document saved successfully'})}
/>
}
isAutoHide={false}
autoHideDuration={5000}
isExiting={false}
onDismiss={() => {}}
/>
);
}
Usage
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.
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.
Don't use a toast for critical errors that block the user. Use Banner for persistent, in-context messaging that requires acknowledgment.
Don't put long or multi-line content in a toast; it disappears after 5 seconds and the user may not finish reading.
Don't show form validation errors as toasts. Use inline field validation so the user can see exactly which field needs fixing.
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 · required
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'.
Anatomy
Body · required
The primary message text describing what happened or what the user should know.
End content · optional
A trailing action like an Undo button or a link, placed after the body text.
Dismiss button · required
A close button that lets the user manually dismiss the toast before auto-hide.
Theming
Targets
astryx-toast
Visual props: type
Variables
--_toast-slide-y · private
Private block-axis offset inherited from ToastViewport for entry and exit motion
