---
title: "Toast"
description: "A single transient notification driven by the toast store."
category: "Overlays"
slug: toast
url: /components/toast
since: "0.1.0"
status: "stable"
---

# Toast

A single transient notification driven by the toast store.

## Import

```svelte
import { Toast } from '@elluzion/iv-ui';
```

## Preview

Info, success, and error; the last one is announced assertively.

```svelte
<script lang="ts">
	import { Button, showToast, Toast } from '@elluzion/iv-ui';
</script>

<div class="row">
	<Button variant="outline" onclick={() => showToast('Build queued for main.', 'info')}>
		Info
	</Button>
	<Button variant="outline" onclick={() => showToast('Deployed to production.', 'success')}>
		Success
	</Button>
	<Button variant="outline" onclick={() => showToast('Deploy failed: exit code 1.', 'error')}>
		Error
	</Button>
	<Toast />
</div>

<style>
	.row {
		display: flex;
		flex-wrap: wrap;
		justify-content: center;
		gap: var(--iv_spacing-sm);
	}
</style>
```

## Usage

- Mount `<Toast />` once in the root layout.
- Call `showToast(message, type, durationMs)`; only one toast is visible at a time.
- `hideToast()` clears it immediately; an id guard stops an old timer from closing a newer toast.

## Examples

### Duration

The third argument sets the visible time in milliseconds.

```svelte
<script lang="ts">
	import { Button, showToast } from '@elluzion/iv-ui';
</script>

<div class="row">
	<Button variant="outline" onclick={() => showToast('Quick confirmation', 'success', 2000)}>
		2 seconds
	</Button>
	<Button variant="outline" onclick={() => showToast('Longer confirmation', 'info', 10000)}>
		10 seconds
	</Button>
</div>

<style>
	.row {
		display: flex;
		flex-wrap: wrap;
		justify-content: center;
		gap: var(--iv_spacing-sm);
	}
</style>
```

### Dismiss

`hideToast()` closes the current toast from your own control.

```svelte
<script lang="ts">
	import { Button, hideToast, showToast } from '@elluzion/iv-ui';
</script>

<div class="row">
	<Button variant="outline" onclick={() => showToast('Waiting for your response…', 'info', 30000)}>
		Show
	</Button>
	<Button variant="ghost" onclick={() => hideToast()}>Dismiss</Button>
</div>

<style>
	.row {
		display: flex;
		flex-wrap: wrap;
		justify-content: center;
		gap: var(--iv_spacing-sm);
	}
</style>
```

### Tokens used

`--iv_border` · `--iv_error` · `--iv_error-dim` · `--iv_font-mono` · `--iv_foreground` · `--iv_info` · `--iv_outline-offset` · `--iv_outline-width` · `--iv_radius-sm` · `--iv_shadow-md` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_success` · `--iv_surface-overlay` · `--iv_surface-raised` · `--iv_text-body` · `--iv_toast-close-size` · `--iv_toast-min-w` · `--iv_z-toast`

See the [token reference](/foundations/tokens.md) for values.

### CSS hooks

`.iv-close` · `.iv-content` · `.iv-toast` · `.iv-toast-error` · `.iv-toast-info` · `.iv-toast-layer` · `.iv-toast-success`

### Functions

| Name | Type | Description |
| --- | --- | --- |
| `showToast(message, type?, durationMs?)` | `(message: string, type?: ToastType, durationMs?: number) => void` | Shows a toast, replacing the current one. The default duration is 5000 ms. |
| `hideToast(id?)` | `(id?: number) => void` | Hides the toast. With an id, only hides it when that toast is still active. |
| `toastState` | `Writable<ToastState \| null>` | Store holding the active toast, or `null` when hidden. |

### Options

| Name | Type | Description |
| --- | --- | --- |
| `type` | `'info' \| 'success' \| 'error'` | Controls the icon and accent. Defaults to `info`. |
| `durationMs` | `number` | Visible time in milliseconds; clamped to at least 800 ms. |

## Accessibility

- The layer uses `role="status"` with `aria-live="polite"` for info and success.
- Errors use `role="alert"` with `aria-live="assertive"`.
- The dismiss control has an accessible name.
- Only one toast exists at a time, so messages do not stack up.

## Related

- [Alert](/components/alert.md)
- [Dialog](/components/dialog.md)
- [Popover](/components/popover.md)
- [Badge](/components/badge.md)