# Sonner (Toast Notifications)

## Overview

Sonner is the toast notification system. It displays ephemeral feedback messages that appear at a fixed position on screen (top-right by default), auto-dismiss after a few seconds, and can be dismissed manually. `<Toaster>` is auto-injected by `<XerticaProvider>` — you never need to render it manually.

---

## When to Use

- Confirming user actions: "Saved successfully", "Member added"
- Showing errors from API calls: "Failed to save changes"
- Providing undo affordance after non-destructive actions

## When NOT to Use

- Critical, persistent warnings — use inline `<Alert>` instead.
- Destructive confirmations — use `<AlertDialog>` instead.
- Validation errors in forms — use `<FormMessage>` inside `<FormField>`.

---

## Usage

Import the `toast` function from `sonner` directly — it is re-exported alongside the library:

```tsx
import { toast } from 'sonner';
```

---

## Methods

| Method                                                | Description                                |
| ----------------------------------------------------- | ------------------------------------------ |
| `toast(message)`                                      | Default neutral toast                      |
| `toast.success(message)`                              | Green success toast                        |
| `toast.error(message)`                                | Red error toast                            |
| `toast.warning(message)`                              | Amber warning toast                        |
| `toast.info(message)`                                 | Blue info toast                            |
| `toast.loading(message)`                              | Spinner toast (persistent until dismissed) |
| `toast.promise(promise, { loading, success, error })` | Auto-updates toast based on promise state  |

---

## Examples

### Basic Feedback

```tsx
import { toast } from 'sonner';

// In an event handler
toast.success('Member saved successfully');
toast.error('Failed to connect to server');
toast.warning('Your session expires in 5 minutes');
```

### With Description

```tsx
toast.error('Save failed', {
  description: 'Please check your connection and try again.',
});
```

### Promise Toast (API calls)

```tsx
toast.promise(fetch('/api/save', { method: 'POST', body: JSON.stringify(data) }), {
  loading: 'Saving...',
  success: 'Saved successfully!',
  error: 'Failed to save. Please try again.',
});
```

### With Undo Action

```tsx
toast('Member deactivated', {
  action: {
    label: 'Undo',
    onClick: () => handleReactivate(memberId),
  },
});
```

---

## Configuration

The `<Toaster>` is rendered inside `<XerticaProvider>` with `position="top-right" richColors`. You do not need to customize it unless you need a different position or theme:

```tsx
// Inside XerticaProvider — already set up
<Toaster position="top-right" richColors />
```

---

## AI Rules

- **Never add `<Toaster>` manually** — it is injected by `<XerticaProvider>`.
- Always use `toast.error()` for errors — never `toast()` with a modified className.
- For actions that modify data (save, delete, add), **always provide user feedback** via a toast.
- For API operations, use `toast.promise()` — it provides loading + success + error states automatically.
- Do not use toasts for form validation errors — those go in `<FormMessage>`.

---

## Related Components

- [`Alert`](./alert.md) — Persistent inline messages
- [`AlertDialog`](./alert-dialog.md) — Confirmation modals