Toast
FreeA short message that slides into a corner of the screen after something happened, and goes away by itself.
npx wunderui-cli add toastPlayground
Installation
npx wunderui-cli add toastWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Toaster, ToastProvider, ToastViewport } from "@/components/ui/toast"Then use it. Wrap your app in the Toaster once, and call the hook anywhere below it:
import { Button } from "@/components/ui/button"
import { Toaster, useToast } from "@/components/ui/toast"
function SaveButton() {
const toast = useToast()
return (
<Button onClick={() => toast.add({ type: "success", title: "Settings saved", description: "Your notification preferences were updated." })}>
Save
</Button>
)
}
export function App() {
return (
<Toaster>
<SaveButton />
</Toaster>
)
}Expected result: A Save button. Pressing it slides a toast into the top right corner of the screen, and it goes away after 5 seconds.
When to use
Use Toast for
- A short confirmation after an action: saved, copied, sent, or deleted with an Undo
- The progress of work that runs in the background, from its start to its result
- A message that needs no answer and does no harm if it goes unnoticed
Use something else for
- Alert for a message that belongs to the page and stays until the cause is fixed
- Alert Dialog for a decision people must make before they can go on
Content
Every toast has a title. A description adds the detail, and an action offers the one thing people can do next, such as Undo.
Lifecycle
A toast closes after 5 seconds. Change the timeout, or set it to 0 so the toast stays until closed, and use the promise helper to turn one toast from loading into success or error.
Keyboard interactions
A toast never takes focus from what people are doing. It joins the tab order only when people ask for it with F6.
- F6
- Moves focus to the toasts, the region named Notifications.
- TaborShift+Tab
- Goes through each toast, then its action and its close button.
- EnterorSpace
- Presses the focused action or close button.
- Escape
- Closes the focused toast.
Behavior and motion
How toasts are added, how long they stay, how they stack and what they announce.
- Adding a toast
- The useToast hook returns the manager of the nearest Toaster, with add, close, update, promise and the list of toasts. Adding takes a title, description, type, action, timeout and priority.
- Timing
- A toast closes after 5 seconds, and you can set a timeout or 0 to keep it until closed. The timer pauses while the pointer is over the stack, focus is inside it or the window is in the background.
- Stack
- The newest toast is in front, and older ones sit lower, smaller and fainter behind it. Hovering or focusing the stack spreads them into a list, and it shows three at a time.
- Promise
- The promise helper adds a loading toast that doesn't close by itself, then turns it into the success or error toast when the promise settles. A loading toast has no coloured dot.
- Announcing
- The viewport is a polite live region, so a screen reader reads each new toast without interrupting. Give an urgent toast high priority and it is announced as an alert.
- Position and size
- The stack sits 16 px from the top or bottom right corner. A toast is up to 420 px wide, narrower on a small screen, and can be swiped away on touch.
- Previews in these docs
- A toast is fixed to the screen corner. Each preview here is a framed box standing in for the screen, so toasts come in at its corner and stay inside, and it starts with one toast that stays open.
- Opening and closing
- A toast slides in from the right while fading in, and leaves the same way, at slow speed. The stack moves into place on the same timing.
- Reduced motion
- With reduced motion toasts don't slide or scale. They only fade in and out.
Anatomy
The parts of a toast, numbered in the figure. The Toaster, provider and viewport sit around the stack and draw nothing themselves.
The one-line setup. It wraps your app in a provider, renders the viewport and draws every toast, and you pick the corner: top right or bottom right.
- data-slot="toast-viewport"Optional
The fixed region in the corner, a live region labelled Notifications that holds the stack. Toaster already renders it.
- 1data-slot="toast"
One notification, a card with a border and a shadow. Older toasts sit smaller and fainter behind the newest, and hovering or focusing the stack spreads them into a list.
- 2
A small dot showing the type: green for success, red for error, yellow for warning and indigo for info.
- 3data-slot="toast-title"
The bold first line that names the outcome, such as Settings saved.
- 4data-slot="toast-description"Optional
One line of detail under the title. It only appears when the toast has a description.
- 5data-slot="toast-action"Optional
A text button in the link colour, such as Undo. It only appears when the toast has action props with a label and a click handler.
- 6data-slot="toast-close"
A button named Close that closes the toast at once.
- data-slot="toast-content"Optional
- Optional
The provider on its own, with a default timeout of 5000 ms and a stack limit of 3 toasts. Toaster already includes it.
Best practices
- Do
Write the title as the outcome in a few words, such as Settings saved. Use the description only for detail people need, like what to do next.
- Do
Offer Undo for actions people can take back, such as a delete, instead of asking them to confirm first.
- Do
Use the promise helper for work that takes a while, so one toast goes from loading to success or error.
- Do
Add the Toaster once, high in the app, and call the useToast hook only below it.
- Don’t
Don't use a toast for a problem people have to fix. It goes away, so keep an Alert on the page until the cause is gone.
- Don’t
Don't put information in a toast that appears nowhere else. It can be missed or closed, so the result must also show on the page.
- Don’t
Don't fire several toasts for one action. Merge them into one message, since the stack shows three at a time.
- Don’t
Don't make many toasts stay forever with a timeout of 0. Keep that for a warning people must act on.
API reference
Toaster wraps the Base UI toast provider and passes its props on. The provider takes defaults for every toast, and options for a single toast go to add (see Behavior and motion).
The one-line setup. It wraps your app in a provider, renders the viewport and draws every toast, and you pick the corner: top right or bottom right.
| Prop | Type | Default | Description |
|---|---|---|---|
| position | "top-right" | "bottom-right" | "top-right" | The corner the stack lives in: or . by default. |
| children required | ReactNode | — |
The provider on its own, with a default timeout of 5000 ms and a stack limit of 3 toasts. Toaster already includes it.
| Prop | Type | Default | Description |
|---|---|---|---|
| timeout | number | 5000 | How long a toast stays before it closes, in milliseconds. 5000 by default; keeps toasts until they are closed. A single toast can set its own . |
| limit | number | 3 | The most toasts that are shown at once. Older ones wait behind the others and are marked . 3 by default. |
| toastManager | ToastManager | — | A toast manager created outside React, so toasts can be added from code that is not a component, such as a fetch wrapper. |
| children | ReactNode | — |
The fixed region in the corner, a live region labelled Notifications that holds the stack. Toaster already renders it.
| Prop | Type | Default | Description |
|---|---|---|---|
| position | "top-right" | "bottom-right" | "top-right" | The corner the viewport is fixed to: or . by default. |
Notes for AI
Give your coding assistant the Markdown reference instead of screenshots.
get_component("toast")npx wunderui-cli add toastThe full library index for assistants is at /llms.txt.