```
## Installation
```bash
npx starwind@latest add toast
```
## Usage
### Setup
The `Toaster` component must be added once to your page, usually in a common layout file shared between pages so you can trigger toasts from anywhere.
```astro title="src/layouts/Layout.astro"
```
### Basic Usage
Toasts are created using the `toast` function. Import it in a `
```
### Variants
The toast system supports multiple variants for different message types.
```astro
---
import { Button } from "@/components/starwind/button";
---
```
### Promise Toast
Handle async operations with automatic loading, success, and error states.
```astro
---
import { Button } from "@/components/starwind/button";
---
```
### Updating & Dismissing
You can update existing toasts or dismiss them programmatically.
```astro
---
import { Button } from "@/components/starwind/button";
---
```
## API Reference
### Toaster
The container component that renders toast notifications. Add this once to your layout.
| Prop | Type | Default |
|------|------|---------|
| `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-right"` |
| `limit` | `number` | `3` |
| `duration` | `number` | `5000` |
| `gap` | `string` | `"0.5rem"` |
| `peek` | `string` | `"1rem"` |
| `class` | `string` | - |
```astro
```
**Additional Notes:**
- `position`: Where toasts appear on screen
- `limit`: Maximum number of visible toasts (older ones stack behind)
- `duration`: Default auto-dismiss time in milliseconds
- `gap`: Spacing between expanded toasts
- `peek`: How much stacked toasts peek out from behind
### toast()
The main function to create toast notifications.
```ts
import { toast } from "@/components/starwind/toast";
// Simple string
toast("Hello world");
// With options
toast("Title", { description: "Description text" });
// Full options object
toast({
title: "Title",
description: "Description",
variant: "success",
duration: 3000,
});
```
### toast.success() / error() / warning() / info() / loading()
Shorthand methods for creating variant-specific toasts.
```ts
toast.success("Saved successfully");
toast.error("Something went wrong", { description: "Please try again" });
toast.warning("Check your input");
toast.info("New update available");
toast.loading("Processing..."); // Does not auto-dismiss
```
### toast.promise()
Handle async operations with automatic state transitions.
```ts
toast.promise(asyncOperation(), {
loading: "Saving...",
success: "Saved!",
error: "Failed to save",
});
// With dynamic messages
toast.promise(fetchUser(), {
loading: { title: "Loading...", description: "Fetching user data" },
success: (user) => ({ title: "Welcome!", description: `Hello, ${user.name}` }),
error: (err) => `Error: ${err.message}`,
});
```
### toast.update()
Update an existing toast by ID.
```ts
const id = toast("Processing...");
toast.update(id, { title: "Done!", variant: "success" });
```
### toast.dismiss()
Dismiss toasts programmatically.
```ts
const id = toast("Hello");
toast.dismiss(id); // Dismiss specific toast
toast.dismiss(); // Dismiss all toasts
```
### ToastOptions
| Property | Type | Description |
|----------|------|-------------|
| `id` | `string` | Custom ID for the toast |
| `title` | `string` | Main toast message |
| `description` | `string` | Secondary description text |
| `variant` | `"default" \| "success" \| "error" \| "warning" \| "info" \| "loading"` | Visual variant |
| `duration` | `number` | Auto-dismiss time in ms (0 for infinite) |
| `onClose` | `() => void` | Callback when close animation starts |
| `onRemove` | `() => void` | Callback when toast is removed from DOM |