---
title: "Dialog"
description: "A modal surface for focused tasks and confirmations."
category: "Overlays"
slug: dialog
url: /components/dialog
since: "0.1.0"
status: "stable"
---

# Dialog

A modal surface for focused tasks and confirmations.

## Import

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

## Preview

A title, body content, and the close control.

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

	let open = $state(false);
</script>

<div class="stack">
	<Button onclick={() => (open = true)}>Rename project</Button>
	<Dialog {open} title="Rename project" onclose={() => (open = false)}>
		<p class="body">The new name appears in the switcher and in every deploy record.</p>
	</Dialog>
</div>

<style>
	.stack {
		display: flex;
		justify-content: center;
	}

	.body {
		margin: 0;
		color: var(--iv_foreground-dim);
		font-size: var(--iv_text-body);
	}
</style>
```

## Usage

- `open` is required and not bindable; set it to false from `onclose` to complete the close.
- `footer` holds the actions; `size` caps the width.
- Focus is trapped while open and restored on close.

## Examples

### Sizes

One dialog with a switchable `sm`, `md`, or `lg` width.

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

	let open = $state(false);
	let size = $state<'sm' | 'md' | 'lg'>('md');
</script>

<div class="stack">
	<div class="row">
		<Button size="sm" variant="outline" onclick={() => ((size = 'sm'), (open = true))}>Small</Button
		>
		<Button size="sm" variant="outline" onclick={() => ((size = 'md'), (open = true))}
			>Medium</Button
		>
		<Button size="sm" variant="outline" onclick={() => ((size = 'lg'), (open = true))}>Large</Button
		>
	</div>
	<Dialog {open} title="Dialog size" {size} onclose={() => (open = false)}>
		<p class="body">The width is capped at the chosen step; content wraps inside it.</p>
	</Dialog>
</div>

<style>
	.stack {
		display: flex;
		justify-content: center;
	}

	.row {
		display: flex;
		gap: var(--iv_spacing-sm);
	}

	.body {
		margin: 0;
		color: var(--iv_foreground-dim);
		font-size: var(--iv_text-body);
	}
</style>
```

### Footer

Cancel and primary actions rendered in the footer.

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

	let open = $state(false);
	let saved = $state(false);
</script>

<div class="stack">
	<Button variant="primary" onclick={() => (open = true)}>Edit retention</Button>
	<Dialog {open} title="Retention policy" onclose={() => (open = false)}>
		<p class="body">Logs older than the selected window are removed at the next sweep.</p>
		{#snippet footer()}
			<Button variant="ghost" onclick={() => (open = false)}>Cancel</Button>
			<Button
				variant="primary"
				onclick={() => {
					open = false;
					saved = true;
				}}>Save</Button
			>
		{/snippet}
	</Dialog>
	{#if saved}<p class="readout">policy saved</p>{/if}
</div>

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

	.body {
		margin: 0;
		color: var(--iv_foreground-dim);
		font-size: var(--iv_text-body);
	}

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

### Props

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` **required** | `boolean` | `false` | Whether the dialog is visible. Set it to false from `onclose` to complete the close. |
| `title` | `string` | `''` | Dialog title; also used as the accessible name. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Maximum dialog width. |
| `closeOnBackdrop` | `boolean` | `true` | Closes when the backdrop is clicked. |
| `closeOnEscape` | `boolean` | `true` | Closes on Escape. |

`class`, `id`, `style`, `aria-*`, and `data-*` are forwarded through rest props.

### Events

| Event | Handler type | Description |
| --- | --- | --- |
| `close` | `() => void` | Called when the dialog requests to close; set `open = false` in response. |

The legacy `on:name` form is accepted for every event.

### Snippets

| Snippet | Type | Description |
| --- | --- | --- |
| `children` | `Snippet` | Content rendered inside the component. |
| `icon` | `Snippet` | Icon rendered before the title. |
| `footer` | `Snippet` | Actions rendered below the body. |

### Tokens used

`--iv_blur` · `--iv_border` · `--iv_dialog-gap` · `--iv_dialog-lg` · `--iv_dialog-md` · `--iv_dialog-sm` · `--iv_ease-in-out` · `--iv_font-sans` · `--iv_foreground` · `--iv_foreground-dim` · `--iv_overlay` · `--iv_radius-lg` · `--iv_radius-sm` · `--iv_ring` · `--iv_ring-width` · `--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_transition-base` · `--iv_z-overlay`

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

### CSS hooks

`.iv-backdrop` · `.iv-body` · `.iv-body-no-title` · `.iv-close-btn` · `.iv-dialog` · `.iv-dialog-lg` · `.iv-dialog-sm` · `.iv-footer` · `.iv-header` · `.iv-icon-slot` · `.iv-title-area`

## Accessibility

| Keys | Action |
| --- | --- |
| `Tab` | Cycles focus inside the dialog. |
| `Escape` | Closes the dialog unless `closeOnEscape` is false. |

- The surface uses `role="dialog"` and `aria-modal="true"`.
- `title` is used for `aria-labelledby`; the body is linked through `aria-describedby`.
- The backdrop click only closes when the click starts on the backdrop itself.

## Related

- [Sheet](/components/sheet.md)
- [AlertDialog](/components/alert-dialog.md)
- [Popover](/components/popover.md)
- [Card](/components/card.md)