Toast

Preview

Design guidance

Use a toast to confirm a brief result or offer one immediate recovery action. Keep the title short. Add a description only when it adds useful context. The action and dismiss control belong inside the toast. Keep important or blocking problems in the page or a dialog as well.

The provider manages timing, updates, promise states, and dismissal. The toaster owns one fixed viewport. It starts at the lower right, expands on hover or focus, and keeps older notifications available through View all.

Installation

Install Toast and its Button/IconButton dependencies.

npx shadcn@latest add https://ghost-ui.com/r/toast.json

Basic usage

Mount one provider and one toaster. Add notifications from any child with the manager hook.

1234567891011import { Button } from "@/components/ui/button";
import { Toast } from "@/components/ui/toast";

function Save() {
  const manager = Toast.useToastManager();
  return <Button onClick={() => manager.add({ title: "Draft saved" })}>Save</Button>;
}

function App() {
  return <Toast.Provider><Save /><Toast.Toaster /></Toast.Provider>;
}

Structures

Toast.Provider wraps Base UI timing and manager behavior. Toast.Toaster renders one Portal and Viewport for the provider's current items. It composes each item from Root, Content, Title, Description, Action, and Close. Provide an optional leading icon with data.icon; place action content in actionProps. Toast.Action preserves Base UI callback, render, ref, and class behavior. The lower-level Portal, Viewport, Positioner, and Arrow parts remain available for custom compositions.

Examples

The examples share this host. Save it beside toast.tsx as toast-provider.tsx and wrap the examples once with ToastDemoProvider.

1234567891011121314151617181920212223"use client";

import * as React from "react";
import { Toast, type ToastPosition } from "@/components/ui/toast";

const PositionContext = React.createContext<{ position: ToastPosition; setPosition: (value: ToastPosition) => void } | null>(null);

export function useToastDemoPosition() {
  const context = React.useContext(PositionContext);
  if (!context) throw new Error("Toast demos require ToastDemoProvider.");
  return context;
}

export function ToastDemoProvider({ children }: { children: React.ReactNode }) {
  const [position, setPosition] = React.useState<ToastPosition>("bottom-right");
  const context = React.useMemo(() => ({ position, setPosition }), [position]);
  return <PositionContext.Provider value={context}>
    <Toast.Provider timeout={3500} limit={3}>
      {children}
      <Toast.Toaster position={position} maxVisible={5} />
    </Toast.Provider>
  </PositionContext.Provider>;
}

Simple

A short result needs only a title.

Icon

Add a caller-owned icon when it helps identify the result.

Types

Use the semantic type to show success, warning, error, or information.

Undo action

The action restores the local saved state before the toast closes.

Persistent reminder

Set timeout to zero when the user must dismiss the message.

Stack

Add six persistent updates to inspect collapsed cards, View all, scrolling, and Clear all.

Promise

Base UI updates one toast as the local promise resolves or rejects.

Position

Move the shared viewport to any corner or edge center.

Duplicate event

Adding the same ID again updates the existing notification.

API reference

Toast re-exports the installed Base UI manager and lower-level parts. See the Base UI Toast API for inherited props and manager options.

The manager's add, update, close, and promise methods preserve Base UI lifecycle behavior. Passing an existing ID to add updates that toast in place.