Skip to content
WunderUI

Toast

Free

A short message that slides into a corner of the screen after something happened, and goes away by itself.

npx wunderui-cli add toast

Playground

Installation

bash
npx wunderui-cli add toast

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

tsx
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:

tsx
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.
TaborShiftTab
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.

  • data-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.

  • A small dot showing the type: green for success, red for error, yellow for warning and indigo for info.

  • data-slot="toast-title"

    The bold first line that names the outcome, such as Settings saved.

  • data-slot="toast-description"Optional

    One line of detail under the title. It only appears when the toast has a description.

  • data-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.

  • data-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.

PropTypeDefaultDescription
position"top-right" | "bottom-right""top-right"The corner the stack lives in: or . by default.
children requiredReactNode—

The provider on its own, with a default timeout of 5000 ms and a stack limit of 3 toasts. Toaster already includes it.

PropTypeDefaultDescription
timeoutnumber5000How 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 .
limitnumber3The most toasts that are shown at once. Older ones wait behind the others and are marked . 3 by default.
toastManagerToastManager—A toast manager created outside React, so toasts can be added from code that is not a component, such as a fetch wrapper.
childrenReactNode—

The fixed region in the corner, a live region labelled Notifications that holds the stack. Toaster already renders it.

PropTypeDefaultDescription
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.

MCPget_component("toast")
Installnpx wunderui-cli add toast

The full library index for assistants is at /llms.txt.