Toast

Overview

The Toast primitive provides consistent, styled notifications. Use the exported toast helper to trigger messages and mount a single <Toaster /> once near the root of your app.

Usage

import { toast, Toaster } from "@tilt-legal/cubitt-components/primitives";

// Mount Toaster once near the root of your app
export function AppLayout({ children }: { children: React.ReactNode }) {
  return (
    <>
      {children}
      <Toaster />
    </>
  );
}

// Trigger a toast from anywhere
toast("Settings saved");

toast.success("Saved with description", {
  description: "We updated your preferences.",
});

toast.error("Something went wrong");
toast.warning("Please review before continuing");
toast.info("New update available");

Examples

Variants

toast("Default toast message");
toast.success("Operation completed successfully");
toast.error("Something went wrong");
toast.warning("Please review before continuing");
toast.info("New update available");

With Description

toast("Document saved", {
  description: "Your changes have been saved to the cloud."
});

toast.success("Upload complete", {
  description: "3 files uploaded successfully."
});

toast.error("Upload failed", {
  description: "Please check your connection and try again."
});

Buttons

Toasts support action (primary) and cancel (secondary) buttons. For a close button (X), pass closeButton to the <Toaster />.

// Action button only
toast("File archived", {
  action: {
    label: "Undo",
    onClick: () => console.log("Undo"),
  },
});

// Cancel button only
toast("Discard changes?", {
  cancel: {
    label: "Cancel",
    onClick: () => console.log("Cancelled"),
  },
});

// Both buttons
toast("Delete this item?", {
  action: {
    label: "Delete",
    onClick: () => console.log("Deleted"),
  },
  cancel: {
    label: "Keep",
    onClick: () => console.log("Kept"),
  },
});

// Enable close button globally
<Toaster closeButton />

Promise

toast.promise(saveWorkspace(), {
  loading: "Saving changes...",
  success: "Changes saved!",
  error: "Failed to save",
});

API Reference

Toaster

Mount once near the root of your app to render toast notifications.

Prop	Type	Default	Description
`position`	`"top-left"` \| `"top-center"` \| `"top-right"` \| `"bottom-left"` \| `"bottom-center"` \| `"bottom-right"`	`"bottom-right"`	Position of toasts on screen.
`duration`	`number`	`4000`	Default duration in ms before toasts auto-dismiss.
`closeButton`	`boolean`	`false`	Show close button on all toasts.
`richColors`	`boolean`	`false`	Use richer colors for different toast types.
`expand`	`boolean`	`false`	Expand toasts by default.
`visibleToasts`	`number`	`3`	Maximum number of visible toasts.
`offset`	`string` \| `number`	-	Offset from the edges of the screen.
`dir`	`"ltr"` \| `"rtl"` \| `"auto"`	`"auto"`	Text direction.
`hotkey`	`string[]`	`["altKey", "KeyT"]`	Keyboard shortcut to focus toasts.
`theme`	`"light"` \| `"dark"` \| `"system"`	`"light"`	Color theme for toasts.
`gap`	`number`	`14`	Gap between toasts in pixels.

toast()

Function to trigger toast notifications. Returns a toast ID that can be used to dismiss or update the toast.

const toastId = toast("Message");
toast.dismiss(toastId);

Methods

Method	Description
`toast(message, options?)`	Show a default toast.
`toast.success(message, options?)`	Show a success toast.
`toast.error(message, options?)`	Show an error toast.
`toast.warning(message, options?)`	Show a warning toast.
`toast.info(message, options?)`	Show an info toast.
`toast.loading(message, options?)`	Show a loading toast.
`toast.promise(promise, options)`	Show loading/success/error based on promise state.
`toast.dismiss(toastId?)`	Dismiss a specific toast or all toasts.

Options

Prop	Type	Default	Description
`description`	`string` \| `ReactNode`	-	Secondary text below the main message.
`duration`	`number`	`4000`	Duration in ms before auto-dismiss. Use `Infinity` to persist.
`position`	`Position`	-	Override the default position for this toast.
`action`	`{ label: string, onClick: () => void }`	-	Primary action button.
`cancel`	`{ label: string, onClick: () => void }`	-	Secondary/cancel button.
`id`	`string` \| `number`	-	Custom ID for the toast. Useful for updating or preventing duplicates.
`onDismiss`	`(toast) => void`	-	Callback when toast is dismissed.
`onAutoClose`	`(toast) => void`	-	Callback when toast auto-closes.
`dismissible`	`boolean`	`true`	Whether the toast can be dismissed by swiping.
`icon`	`ReactNode`	-	Custom icon to display.
`classNames`	`object`	-	Custom class names for toast parts.

Toast

On this page