

<Preview name="BasicToastExample" />

## Overview [#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 [#usage]

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

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

```tsx
// 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 [#examples]

### Variants [#variants]

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="VariantToastExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    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");
    ```
  </Tab>
</Tabs>

### With Description [#with-description]

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="VariantWithDescriptionToastExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    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."
    });
    ```
  </Tab>
</Tabs>

### Buttons [#buttons]

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

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="ButtonsToastExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    // 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 />
    ```
  </Tab>
</Tabs>

### Promise [#promise]

<Tabs items="['Preview', 'Code']">
  <Tab value="Preview">
    <Preview name="PromiseToastExample" />
  </Tab>

  <Tab value="Code">
    ```tsx
    toast.promise(saveWorkspace(), {
      loading: "Saving changes...",
      success: "Changes saved!",
      error: "Failed to save",
    });
    ```
  </Tab>
</Tabs>

## API Reference [#api-reference]

### Toaster [#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() [#toast]

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

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

#### Methods [#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 [#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.                                    |