Toast

A toast is a brief, self-dismissing message that confirms an action or reports a result without blocking the page. Call toast() from anywhere to show one. Use it for transient feedback like "Saved" or "Upload failed", not for content the user must act on (use Dialog or Alert Dialog there).

Preview

Installation

npx shadcn@latest add @cubby-ui/toast

Usage

import { toast } from "@/components/ui/cubby-ui/toast"

toast({
  title: "Event has been created",
  description: "Friday, February 10, 2023 at 5:57 PM"
})

Examples

Types

Use type (or the toast.success, toast.error, and similar shorthands) to set the toast's color and icon.

Anchored Toast

Use toast.anchored() to pin a toast to a specific element for contextual feedback like a "Copied" confirmation.

With Action

Use the action option to add a button; clicking it dismisses the current toast and can trigger a follow-up.

Deduplicated

Pass a fixed id to collapse repeats; a matching toast updates in place with a pulse instead of stacking a duplicate.

Promise

Use toast.promise() to drive loading, success, and error states from a promise's resolution.

Varying Heights

Toasts measure their own height and adjust the stack when content sizes differ.

Grouped Toasts

Use toast.grouped() to fold related toasts into one summary with an expandable card, for long-running work like deployments or uploads.

Accessibility

Announcement urgency

Use priority to control how a screen reader announces the toast. "low" (the default) announces politely without interrupting the user; reserve "high" for messages that must break through, such as a failed save.

toast.error({ title: "Couldn't save", priority: "high" });

API Reference

The Toast component is built on top of Base UI's Toast. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Toast documentation.

Props

toast()

Programmatically displays toast notifications. Supports object-based and JSX-based call signatures.

// Object-based (recommended)
toast({ title: "Success", description: "Your changes have been saved", type: "success" });
 
// JSX-based
toast(<div>Custom JSX content</div>, { type: "info" });

Helper Methods

Type-specific methods for common toast types and programmatic control.

// Type variants
toast.success({ title: "Saved!" });
toast.error({ title: "Failed" });
toast.warning({ title: "Warning" });
toast.info({ title: "Info" });
 
// Async operations - toast.promise() handles loading/success/error automatically
toast.promise(saveData(), {
  loading: "Saving...",
  success: "Saved!",
  error: "Failed to save",
});
 
// With dynamic messages based on promise result
toast.promise(fetchData(), {
  loading: { title: "Loading...", description: "Fetching data" },
  success: (data) => ({ title: "Success!", description: `Loaded ${data.name}` }), // data = resolved value
  error: (err) => ({ title: "Error", description: err.message }), // err = Error object
});
 
// Manual control (for advanced use cases)
// All toast methods return an ID that can be used for updates or dismissal
const toastId = toast({ title: "Processing..." });
toast.update(toastId, { title: "Done!", type: "success" });
toast.dismiss(toastId);

toast.anchored()

Shows toasts anchored to a specific element, useful for contextual feedback like "Copied" confirmations. Inherits all base toast options except type.

toast.anchored({
  description: "Copied!",
  anchor: buttonRef,
  side: "top",
  sideOffset: 8,
  arrow: true,
  duration: 2000,
});
 
// Dismiss an anchored toast
toast.dismissAnchored(toastId);

toast.grouped()

Groups multiple related toasts into a single collapsible summary. When only one item exists, it renders as a normal toast. When multiple items share the same groupId, they collapse into a summary with a "Show" button that reveals an expandable card.

toast.grouped({
  groupId: "deployments",
  title: "Deployment abc123 is building...",
  type: "loading",
  action: { label: "Cancel", onClick: () => cancelDeployment() },
  groupSummary: ({ loadingCount }) => `${loadingCount} deployments in progress`,
  groupAction: { label: "Show", expandedLabel: "Hide" },
});

GroupSummaryCounts

The groupSummary function receives a GroupSummaryCounts object with these fields:

• loadingCount - Items currently in loading state (reflects visible items)
• completedCount - Total items that have completed (historical, persists after dismiss)
• totalCount - loadingCount + completedCount
• successCount - Items completed with type "success" (historical)
• errorCount - Items completed with type "error" (historical)
• warningCount - Items completed with type "warning" (historical)
• infoCount - Items completed with type "info" (historical)

Helper methods:

// Dismiss a single item from a group
toast.dismissGroupItem(itemId);
 
// Dismiss an entire group
toast.dismissGroup(groupId);
 
// Update a specific item (e.g., loading -> success)
toast.updateGroupItem(itemId, { title: "Deployed!", type: "success" });
 
// Dismiss a completed item (removes from progress state)
toast.dismissCompletedItem(itemId);

Behavior:

• Single item: Renders as a normal toast with close button
• Multiple items: Collapses into summary with Show/Hide button
• Loading items: Groups persist until all loading items complete or are dismissed
• Icon derivation: Shows loading spinner while any item has type: "loading", then success/warning/error based on results

toast.groupedPromise()

Shows a grouped toast that resolves with a promise, handling loading/success/error states automatically. Supports cancellation via AbortSignal.

const controller = new AbortController();
 
await toast.groupedPromise(
  uploadFile(file),
  {
    loading: { title: "Uploading...", action: { label: "Cancel", onClick: () => controller.abort() } },
    success: (data) => ({ title: "Uploaded!", description: data.filename }),
    error: (err) => ({ title: "Failed", description: err.message }),
    aborted: { title: "Cancelled" }, // Optional
  },
  {
    groupId: "uploads",
    groupSummary: ({ loadingCount, completedCount }) =>
      loadingCount > 0 ? `${loadingCount} uploading...` : `${completedCount} uploaded`,
    signal: controller.signal,
  }
);

All other GroupedToastOptions props (groupId, groupSummary, groupAction, etc.) are also supported.

ToastProvider

Wraps your app to enable stacked toast notifications. Composes Base UI's Toast.Provider, Toast.Portal, and Toast.Viewport.

AnchoredToastProvider

Wraps your app to enable anchored toasts (positioned relative to elements). Composes Base UI's Toast.Provider, Toast.Portal, and Toast.Viewport.

Setup

Wrap your app with both providers to enable all toast functionality:

// app/layout.tsx or similar
import { ToastProvider, AnchoredToastProvider } from "@/registry/default/toast/toast";
 
export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <ToastProvider position="bottom-right">
          <AnchoredToastProvider>
            {children}
          </AnchoredToastProvider>
        </ToastProvider>
      </body>
    </html>
  );
}