Toast

When Not to UseCopy Anchor Link

• for a toast in a product (use Sonner, which also has the rules for the content of a toast)
• for a status that lasts (use an Alert)
• for a decision before an action (use an Alert Dialog)

See Alert for a comparison of the Alert, the toast, and the Alert Dialog.

AnatomyCopy Anchor Link

* The title is the accessible name of the Toast, which is a dialog.

Toaster renders each Toast from these parts, in this order. The action is shown when the Toast has actionProps. If the Toast has a type, an icon is also shown before the title; the figure doesn’t show it.

TypesCopy Anchor Link

type accepts any string. The types success, info, warning, error, and loading show an icon, which is listed under ToastIcon, and any other value shows none. See Sonner for the purpose of each type.

BehaviorCopy Anchor Link

Toaster renders the stack in a portal at the end of body, and toast.add adds a Toast to it from anywhere in the app. When a Toast appears, focus doesn’t move, and the page stays interactive.

DurationCopy Anchor Link

By default, a Toast disappears after 5 seconds. To change the duration for all Toasts, set timeout on Toaster. To change it for one Toast, pass timeout to toast.add; if timeout is 0, the Toast doesn’t disappear by itself. A Toast of type loading has no timer. The timers are paused while the pointer or focus is in the stack.

DismissalCopy Anchor Link

A Toast is dismissed when users click the close button, press Escape while focus is in the Toast, or swipe it to the right or down. A click on the action doesn’t dismiss the Toast, so close the Toast in the action’s onClick.

StackCopy Anchor Link

By default, the stack shows three Toasts. To change the number, set limit on Toaster. A Toast over the limit is inert and invisible until a place is free. When the pointer or focus is in the stack, the stack expands, and all Toasts are shown in full.

Position and SizeCopy Anchor Link

The stack is fixed at the bottom of the screen, at the end edge from 640px. See Layout for its width and Elevation for the order of the layers.

AccessibilityCopy Anchor Link

Base UI’s Toast sets the roles, announces each Toast, and moves focus into the stack when users press F6.

The label of the close button is “Close toast” by default. To translate it, use the Summit Provider.

If you pass priority: 'high', the Toast has role="alertdialog", and its title and description are placed in a role="alert" element, which screen readers announce immediately. Pass both as strings.

RequirementsCopy Anchor Link

The two requirements of a toast on Sonner apply to this Toast too. If a Toast must not disappear, pass timeout: 0.

InstallationCopy Anchor Link

npx shadcn@latest add @summit/toast

The CLI also adds @summit/button, @summit/summit-provider, and @summit/toast-icon.

UsageCopy Anchor Link

Render Toaster once, around the app, and call toast.add from any event handler.

import { Button } from '@/components/ui/button';
import { toast, Toaster } from '@/components/ui/toast';

<Toaster>
    <Button variant="outline" onClick={() => toast.add({ title: 'Invoice sent' })}>
        Send invoice
    </Button>
</Toaster>;

With an ActionCopy Anchor Link

To add an action, pass the props of the action button in actionProps. toast.add returns the id that you pass to toast.close.

const id = toast.add({
    title: 'Invoice sent',
    description: 'Atelier Brume will get it by email.',
    actionProps: {
        children: 'Undo',
        onClick: () => {
            unsend(invoice);
            toast.close(id);
        },
    },
});

Follow a RequestCopy Anchor Link

To follow a request in one Toast, use toast.promise, which sets the type to loading, and then to success or error. If you pass a string in place of an object, the string becomes the description, and the Toast has no title.

toast.promise(sendInvoice(invoice), {
    loading: { title: 'Sending the invoice' },
    success: { title: 'Invoice sent' },
    error: { title: 'The invoice was not sent' },
});

Change the Limit and the TimeoutCopy Anchor Link

To change the limit and the timeout for all Toasts, set limit and timeout on Toaster.

<Toaster limit={1} timeout={8000} />

API ReferenceCopy Anchor Link

The parts accept the props of their matching parts in Base UI’s Toast, where Toast is Toast.Root. See the Base UI Toast documentation for swipeDirection and render.

ToasterCopy Anchor Link

createToastManager returns a manager to pass to toastManager. useToastManager is a hook that returns the Toasts and the methods of the manager.

toastCopy Anchor Link

toast.add accepts these options.

See the Base UI Toast documentation for onClose, onRemove, and data.

ToastIconCopy Anchor Link

ToastIcon is the registry item toast-icon. The CLI installs it with this Toast and with Sonner, and both render it before the title.

The icon has aria-hidden. For any other type, ToastIcon renders nothing.