---
title: "AlertDialog"
description: "A blocking confirmation that returns a decision through an action."
category: "Overlays"
slug: alert-dialog
url: /components/alert-dialog
since: "0.1.0"
status: "stable"
---

# AlertDialog

A blocking confirmation that returns a decision through an action.

## Import

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

## Preview

A title, a message, and a cancel/confirm pair.

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

	let published = $state(0);

	function confirm() {
		showAlertDialog({
			title: 'Publish release?',
			message: 'The build will be promoted to production and the current version will be archived.',
			actions: [
				{ label: 'Cancel', variant: 'ghost' },
				{
					label: 'Publish',
					variant: 'primary',
					onClick: () => (published += 1)
				}
			]
		});
	}
</script>

<div class="stack">
	<Button variant="primary" onclick={confirm}>Publish release</Button>
	<p class="readout">published {published} times</p>
	<AlertDialog />
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		align-items: center;
		gap: var(--iv_spacing-sm);
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

## Usage

- Mount `<AlertDialog />` once in the root layout, then open it with `showAlertDialog({ ... })`.
- `actions` defaults to a single `OK` button; give each action a `variant` that matches its weight.
- Set `closeOnClick: false` to keep the dialog open, then close it yourself when the work finishes.

## Examples

### Destructive

A danger action with the delete verb in the label.

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

	let deleted = $state(false);

	function remove() {
		showAlertDialog({
			title: 'Delete project?',
			message: 'Orbital and its deployments will be removed. This cannot be undone.',
			actions: [
				{ label: 'Cancel', variant: 'ghost' },
				{
					label: 'Delete project',
					variant: 'danger',
					onClick: () => (deleted = true)
				}
			]
		});
	}
</script>

<div class="stack">
	<Button variant="danger" onclick={remove}>Delete project</Button>
	{#if deleted}<p class="readout">project deleted</p>{/if}
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		align-items: center;
		gap: var(--iv_spacing-sm);
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_error);
	}
</style>
```

### Custom actions

Several actions, each with its own variant and handler.

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

	let last = $state('none');

	function choose() {
		showAlertDialog({
			title: 'Unsaved changes',
			message: 'Leave the editor and lose the draft, or keep working?',
			closeOnBackdrop: false,
			actions: [
				{
					label: 'Keep editing',
					variant: 'ghost',
					onClick: () => (last = 'keep editing')
				},
				{
					label: 'Discard',
					variant: 'danger',
					onClick: () => (last = 'discarded')
				},
				{
					label: 'Save draft',
					variant: 'primary',
					onClick: () => (last = 'saved')
				}
			]
		});
	}
</script>

<div class="stack">
	<Button variant="outline" onclick={choose}>Close editor</Button>
	<p class="readout">last choice: {last}</p>
</div>

<style>
	.stack {
		display: flex;
		flex-direction: column;
		align-items: center;
		gap: var(--iv_spacing-sm);
	}

	.readout {
		margin: 0;
		font-family: var(--iv_font-mono);
		font-size: var(--iv_text-sm);
		color: var(--iv_foreground-dim);
	}
</style>
```

### Tokens used

`--iv_blur` · `--iv_border` · `--iv_dialog-gap` · `--iv_dialog-sm` · `--iv_font-sans` · `--iv_font-ui` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_leading-base` · `--iv_overlay` · `--iv_radius-lg` · `--iv_shadow-lg` · `--iv_spacing-2xl` · `--iv_spacing-lg` · `--iv_spacing-md` · `--iv_spacing-sm` · `--iv_spacing-xl` · `--iv_surface-raised` · `--iv_text-xl` · `--iv_z-overlay`

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

### CSS hooks

`.iv-alertdialog` · `.iv-alertdialog-actions` · `.iv-alertdialog-message` · `.iv-alertdialog-title` · `.iv-backdrop`

### Functions

| Name | Type | Description |
| --- | --- | --- |
| `showAlertDialog(config)` | `AlertDialogState` | Opens the dialog with the given title, message, and actions. |
| `alertDialogState` | `Writable<AlertDialogState \| null>` | Store holding the current dialog, or `null` when closed. |

### Config

Passed to `showAlertDialog`.

| Name | Type | Description |
| --- | --- | --- |
| `title` | `string` | Dialog title and accessible name. |
| `message` | `string` | Body text describing the decision. |
| `actions` | `AlertDialogAction[]` | Buttons rendered in order; defaults to one `OK` action. |
| `closeOnBackdrop` | `boolean` | Closes when the backdrop is clicked. Defaults to `true`. |
| `closeOnEscape` | `boolean` | Closes on Escape. Defaults to `true`. |
| `onclose` | `() => void` | Called after the dialog closes for any reason. |

### Action

| Name | Type | Description |
| --- | --- | --- |
| `label` | `string` | Button text. |
| `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'danger'` | Button emphasis. |
| `size` | `'sm' \| 'md' \| 'lg'` | Button size. |
| `disabled` | `boolean` | Disables the action. |
| `closeOnClick` | `boolean` | Closes the dialog after the handler runs. Defaults to `true`. |
| `onClick` | `() => void` | Runs before the dialog closes. |

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Moves focus between the actions. |
| `Escape` | Closes the dialog unless `closeOnEscape` is false. |

- The surface uses `role="alertdialog"` and `aria-modal="true"`.
- Focus is trapped while open and restored when the dialog closes.
- The title names the dialog; the message is linked through `aria-describedby`.

## Related

- [Dialog](/components/dialog.md)
- [Sheet](/components/sheet.md)
- [Toast](/components/toast.md)
- [Button](/components/button.md)