Toast

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

Toast variants for different feedback scenarios: success, error, warning, and info.

Anchored Toast

Toasts can be anchored to a specific element, useful for contextual feedback like "Copied" confirmations.

With Action

Add action buttons to toasts. Clicking the action dismisses the current toast and can trigger follow-up toasts.

Promise

Show loading, success, and error states based on promise resolution.

Varying Heights

Toasts automatically adjust their stacking when content has different heights.

Grouped Toasts

Group multiple related toasts into a single summary toast with an expandable card. Ideal for long-running operations like deployments or file uploads.

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" },
});

Prop

Type

Default

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" });

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,
  }
);

Prop

Type

Default

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.

Prop

Type

Default

AnchoredToastProvider

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

Prop

Type

Default

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>
  );
}

Preview

Installation

Usage

Examples

Types

Anchored Toast

With Action

Promise

Varying Heights

Grouped Toasts

API Reference

Props

toast()

Helper Methods

toast.anchored()

toast.grouped()

toast.groupedPromise()

ToastProvider

AnchoredToastProvider

Setup

On this page