# Toast

> A notification system: call toast() from anywhere to queue one, mount <Toaster /> once to render the stack — success, error, info and loading variants, an optional action, and accessible live-region announcements.

- Package: `fancy-ui-svelte` (Svelte 5 + Tailwind CSS v4)
- Category: Overlays
- Tags: overlay, toast, notification, snackbar, live-region, accessibility
- Docs: https://fancy-ui.rama.app/docs/components/toast
- Source: https://github.com/RamaHerbin/fancy-ui/tree/main/src/lib/fancy-ui/toast

## Import

```svelte
<script lang="ts">
  import { Toast } from 'fancy-ui-svelte';
</script>
```

Setup (once per project): `npm install fancy-ui-svelte`, then add `@import "fancy-ui-svelte/tailwind.css";` after `@import "tailwindcss";` in your main CSS file. Full guide: https://fancy-ui.rama.app/llms.txt

React: `import { Toast } from 'fancy-ui-react';` (same prop names; `class` becomes `className`, snippets become `ReactNode`).

## Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `position` | `"top-left" \| "top-center" \| "top-right" \| "bottom-left" \| "bottom-center" \| "bottom-right"` | `"bottom-right"` | Corner (or edge-center) the <Toaster /> stack anchors to |
| `class` | `string` | — | Additional classes for the viewport that stacks the toasts |
| `ref` | `HTMLDivElement \| null` | `null` | Bindable reference to the <Toaster /> root node |
| `sound` | `boolean` | `false` | Plays success or error when a toast of that variant appears, once the user has enabled sound |
| `toast().title` (required) | `string` | — | Primary line of the toast raised by the toast() function |
| `toast().description` | `string` | — | Secondary line, shown under the title |
| `toast().variant` | `"success" \| "error" \| "info" \| "loading"` | `"info"` | Icon, accent colour, and the live region it announces through — error is assertive, everything else polite |
| `toast().duration` | `number` | `5000` | Milliseconds before auto-dismiss; Infinity is sticky. Defaults to Infinity for the loading variant, which has no natural finish time |
| `toast().action` | `{ label: string; onClick: () => void }` | — | A single action button. Auto-dismiss pauses on hover or focus for every toast, with or without one |

## Examples

### Basic Usage

Call toast() from a click handler; <Toaster /> renders the result.

```svelte
<script lang="ts">
	import { Button } from "fancy-ui-svelte";
	import { Toaster, toast } from "fancy-ui-svelte";

	function show() {
		toast({
			title: "Theme saved",
			description: "CSS copied to the clipboard.",
			variant: "success",
		});
	}
</script>

<Toaster sound />
<Button onclick={show}>Show toast</Button>
```

### Variants

Success, error, info and loading, side by side.

```svelte
<script lang="ts">
	import { Button } from "fancy-ui-svelte";
	import { Toaster, toast } from "fancy-ui-svelte";

	function showSuccess() {
		toast({
			title: "Theme saved",
			description: "CSS copied to the clipboard.",
			variant: "success",
		});
	}

	function showError() {
		toast({ title: "Failed to send", description: "Check your connection.", variant: "error" });
	}

	function showInfo() {
		toast({ title: "New version available", variant: "info" });
	}

	function showLoading() {
		toast({ title: "Publishing…", variant: "loading" });
	}
</script>

<Toaster sound />
<div class="flex flex-wrap gap-2">
	<Button variant="outline" onclick={showSuccess}>Success</Button>
	<Button variant="outline" onclick={showError}>Error</Button>
	<Button variant="outline" onclick={showInfo}>Info</Button>
	<Button variant="outline" onclick={showLoading}>Loading</Button>
</div>
```

### With Action

An error toast carrying a Retry action.

```svelte
<script lang="ts">
	import { Button } from "fancy-ui-svelte";
	import { Toaster, toast } from "fancy-ui-svelte";

	function send() {
		toast({
			title: "Failed to send",
			description: "Check your connection.",
			variant: "error",
			action: {
				label: "Retry",
				onClick: send,
			},
		});
	}
</script>

<Toaster sound />
<Button variant="outline" onclick={send}>Simulate a failed request</Button>
```

### Persistent

duration: Infinity — dismissed only by the user, never automatically.

```svelte
<script lang="ts">
	import { Button } from "fancy-ui-svelte";
	import { Toaster, toast } from "fancy-ui-svelte";

	function show() {
		// duration: Infinity — sticky. Only the toast's own close button (or
		// dismissToast(id)) removes it.
		// `info` toasts stay silent by design — only outcomes chime.
		toast({
			title: "Reviewing your changes",
			description: "This stays until you dismiss it yourself.",
			variant: "info",
			duration: Infinity,
		});
	}
</script>

<Toaster sound />
<Button variant="outline" onclick={show}>Show a persistent toast</Button>
```