Overlay
Toast
A brief, self-dismissing message that confirms an action or reports a result without interrupting the flow. Toasts stack in a corner, auto-expire, and can carry a single quick action like Undo.
npx shadcn@latest add @orbit/toastOverview
Each button spawns a real toast that slides in, counts down, and dismisses itself. Fire several to see them stack — hover the stack to expand it and pause the timers.
Variants
A leading icon and accent communicate the result at a glance. Shown inline here for reference — real toasts are fired through the toast API.
Anatomy & options
Keep a toast to a short title, an optional second line, and at most one action. A countdown bar can show the time remaining.
Position & promises
Toasts can anchor to any corner or the top/bottom center. toast.promise() shows a loading toast that resolves in place to a success or error once an async task settles — try the “Loading → done” button in each.
Props
Mount one <Toaster> per stack — wrap a subtree and fire with useToast(), or pass the exported toastManager and fire with the global toast API from anywhere.
| Prop | Type | Default | Description |
|---|---|---|---|
| position | "bottom-right" | "bottom-left" | "bottom-center" | "top-right" | "top-left" | "top-center" | "bottom-right" | Corner or edge the stack anchors to, 16px from the viewport edge. |
| limit | number | 3 | Max toasts shown at once; older ones queue behind the stack. |
| timeout | number | 4500 | Provider-level default auto-dismiss delay in ms. |
| toastManager | ToastManager | — | External manager (the exported toastManager) so the imperative toast API can fire from outside React. |
| className | string | — | Extra classes for the 340px viewport. |
| children | ReactNode | — | Subtree that can fire toasts via useToast(). |
toast options
Accepted by toast.add() and the shorthands toast.info/success/warning/error/loading(title, options). toast.update(id, options), toast.dismiss(id?), and toast.promise(promise, { loading, success, error }) complete the API.
| Prop | Type | Default | Description |
|---|---|---|---|
| title | ReactNode | — | Short, verb-first headline. Required. |
| description | ReactNode | — | Optional second line below the title. |
| variant | "info" | "success" | "warning" | "error" | "loading" | "info" | Tone glyph + accent. Errors and warnings are announced assertively. |
| action | { label: string; onClick?: () => void } | — | Single quick action (e.g. Undo). Clicking it also dismisses the toast. |
| duration | number | 4500 | Auto-dismiss delay in ms. 0 persists. Loading toasts default to 0. |
| progress | boolean | false | Shows a countdown bar along the bottom edge while the timer runs. |
| dismissible | boolean | true | Shows the × button. Loading toasts default to false. |
| id | string | — | Re-using an id upserts the toast in place and refreshes its timer. |
| onClose | () => void | — | Called when the toast closes — timer, swipe, ×, or action. |
Usage
Toasts are transient — never put anything critical only in one.
Confirm actions briefly
“Task created”, “Changes saved” — a quick acknowledgment the user can ignore.
Put critical info only in a toast
It disappears in seconds. Errors that block work belong inline or in a dialog.
Offer Undo for reversible actions
A single action like Undo turns a toast into a safety net for bulk changes.
Stack more than a few
Cap the visible count and queue the rest; a wall of toasts is just noise.
Keyboard & accessibility
Toasts render in a live region: info and success announce politely (role=status), errors and warnings assertively (role=alert). F6 jumps focus into the toast landmark to reach actions and the labeled Dismiss button; hovering or focusing the stack pauses auto-dismiss, and toasts can be swiped away. prefers-reduced-motion collapses the entrance and countdown animations.