Skip to content
Statix Design System

Overlays

Dialog

A modal window on a soft navy scrim. Use it when the user has to read something or decide before going on, for example before restoring a backup.

import * as Dialog from '@statix/ui/dialog';

Playground

Controls
<Dialog.Root>
	<Dialog.Trigger>
		{#snippet child({ props })}
			<Button {...props}>Open dialog</Button>
		{/snippet}
	</Dialog.Trigger>
	<Dialog.Content>
		<Dialog.Header>
			<Dialog.Eyebrow>Backup from yesterday, 22:05</Dialog.Eyebrow>
			<Dialog.Title>Restore website as it was yesterday at 22:05?</Dialog.Title>
			<Dialog.Description>Your website is offline for about two minutes. Emails are not affected.</Dialog.Description>
		</Dialog.Header>
		<Dialog.Footer>
			<Dialog.Close>
				{#snippet child({ props })}
					<Button variant="ghost" {...props}>Cancel</Button>
				{/snippet}
			</Dialog.Close>
			<Button>Yes, restore</Button>
		</Dialog.Footer>
	</Dialog.Content>
</Dialog.Root>

Examples

Restore a backup

The dialog from the Penpot board. An eyebrow names the backup, numbered steps say what happens and a hint offers a call with support. The corner close button is off because Cancel does the same job.

<script lang="ts">
	import * as Dialog from '@statix/ui/dialog';
	import { Button } from '@statix/ui/button';
	import PhoneIcon from '@lucide/svelte/icons/phone';
	import RotateCcwIcon from '@lucide/svelte/icons/rotate-ccw';

	const steps = [
		{
			title: 'We back up the current state',
			text: 'If you change your mind, you can go back to it at any time.'
		},
		{
			title: 'We restore the state from yesterday at 22:05',
			text: 'Takes about two minutes. Your website is offline during that time.'
		},
		{
			title: 'Changes since yesterday at 22:05 are gone',
			text: 'This affects 1 changed page (class schedule). Emails are not affected.'
		}
	];
</script>

<Dialog.Root>
	<Dialog.Trigger>
		{#snippet child({ props })}
			<Button {...props}>
				<RotateCcwIcon data-icon="inline-start" />
				Restore website
			</Button>
		{/snippet}
	</Dialog.Trigger>
	<Dialog.Content showCloseButton={false}>
		<Dialog.Header>
			<Dialog.Eyebrow>Backup from yesterday, 22:05</Dialog.Eyebrow>
			<Dialog.Title>Restore website as it was yesterday at 22:05?</Dialog.Title>
		</Dialog.Header>
		<div class="grid gap-5">
			<Dialog.Description class="font-medium text-ink">
				This is what happens, in this order:
			</Dialog.Description>
			<ol class="grid gap-4">
				{#each steps as step, i (step.title)}
					<li class="flex gap-3.5">
						<span
							class="grid size-7 shrink-0 place-items-center rounded-full bg-secondary text-label text-ink"
						>
							{i + 1}
						</span>
						<div class="grid gap-0.5 pt-0.5">
							<p class="font-medium text-ink">{step.title}</p>
							<p class="text-small text-ink-2">{step.text}</p>
						</div>
					</li>
				{/each}
			</ol>
		</div>
		<p
			class="flex items-start gap-3 rounded-lg bg-primary-soft px-4 py-2.5 text-small text-primary-soft-foreground"
		>
			<PhoneIcon class="mt-0.5 size-4 shrink-0" />
			<span>
				Not sure? Jonas will happily do it with you on the phone:
				<a
					href="tel:+4940468970790"
					class="font-medium whitespace-nowrap underline-offset-3 hover:underline"
				>
					040 468 970 790
				</a>
			</span>
		</p>
		<Dialog.Footer>
			<Dialog.Close>
				{#snippet child({ props })}
					<Button variant="ghost" {...props}>Cancel</Button>
				{/snippet}
			</Dialog.Close>
			<Button>Yes, restore</Button>
		</Dialog.Footer>
	</Dialog.Content>
</Dialog.Root>

With a form

A small dialog for one quick edit. The first field gets focus when it opens.

<script lang="ts">
	import * as Dialog from '@statix/ui/dialog';
	import { Button } from '@statix/ui/button';
	import { Input } from '@statix/ui/input';
	import { Label } from '@statix/ui/label';
</script>

<Dialog.Root>
	<Dialog.Trigger>
		{#snippet child({ props })}
			<Button variant="outline" {...props}>Rename website</Button>
		{/snippet}
	</Dialog.Trigger>
	<Dialog.Content size="sm">
		<Dialog.Header>
			<Dialog.Title>Rename website</Dialog.Title>
			<Dialog.Description>
				The name only shows in your customer area. Your domain stays the same.
			</Dialog.Description>
		</Dialog.Header>
		<div class="grid gap-2">
			<Label for="website-name">Name</Label>
			<Input id="website-name" value="Yoga Studio Berger" />
		</div>
		<Dialog.Footer>
			<Dialog.Close>
				{#snippet child({ props })}
					<Button variant="ghost" {...props}>Cancel</Button>
				{/snippet}
			</Dialog.Close>
			<Button>Save name</Button>
		</Dialog.Footer>
	</Dialog.Content>
</Dialog.Root>

Sizes

sm (400px) for short questions, md (560px, default) for most dialogs, lg (720px) for tables or longer text. On phones the dialog is always 16px from the screen edges.

<script lang="ts">
	import * as Dialog from '@statix/ui/dialog';
	import { Button } from '@statix/ui/button';

	const sizes = [
		{ size: 'sm', label: 'Small, 400px' },
		{ size: 'md', label: 'Medium, 560px' },
		{ size: 'lg', label: 'Large, 720px' }
	] as const;
</script>

{#each sizes as { size, label } (size)}
	<Dialog.Root>
		<Dialog.Trigger>
			{#snippet child({ props })}
				<Button variant="outline" {...props}>{label}</Button>
			{/snippet}
		</Dialog.Trigger>
		<Dialog.Content {size}>
			<Dialog.Header>
				<Dialog.Title>Download invoice INV-2026-0412</Dialog.Title>
				<Dialog.Description>
					Business plan for yoga-berger.de, 1 October to 31 October 2026. We send a copy to
					anna@yoga-berger.de as well.
				</Dialog.Description>
			</Dialog.Header>
			<Dialog.Footer showCloseButton>
				<Button>Download PDF</Button>
			</Dialog.Footer>
		</Dialog.Content>
	</Dialog.Root>
{/each}

Controlled

Bind open to close the dialog from code, for example after a request finishes. Disable the buttons while it runs.

<script lang="ts">
	import * as Dialog from '@statix/ui/dialog';
	import { Button } from '@statix/ui/button';
	import { Spinner } from '@statix/ui/spinner';

	let open = $state(false);
	let saving = $state(false);

	async function startBackup() {
		saving = true;
		await new Promise((resolve) => setTimeout(resolve, 1200));
		saving = false;
		open = false;
	}
</script>

<Button variant="outline" onclick={() => (open = true)}>Back up now</Button>

<Dialog.Root bind:open>
	<Dialog.Content size="sm">
		<Dialog.Header>
			<Dialog.Eyebrow>Last backup today at 03:10</Dialog.Eyebrow>
			<Dialog.Title>Back up yoga-berger.de now?</Dialog.Title>
			<Dialog.Description>
				We save your files, database and settings. Your website stays online.
			</Dialog.Description>
		</Dialog.Header>
		<Dialog.Footer>
			<Dialog.Close>
				{#snippet child({ props })}
					<Button variant="ghost" disabled={saving} {...props}>Cancel</Button>
				{/snippet}
			</Dialog.Close>
			<Button onclick={startBackup} disabled={saving}>
				{#if saving}<Spinner data-icon="inline-start" />{/if}
				Start backup
			</Button>
		</Dialog.Footer>
	</Dialog.Content>
</Dialog.Root>

Guidelines

Do

  • Ask a question in the title and answer it with the primary button: "Restore website?" and "Yes, restore".
  • Put Cancel as a ghost button left of the primary action.
  • Say what will happen and what will not. "Emails are not affected" saves a support call.
  • Use an eyebrow for context such as the backup date, not for the main message.

Don't

  • Don’t open a dialog without a user action.
  • Don’t stack dialogs. Close one before opening the next.
  • Don’t use a dialog for a destructive confirmation; use Alert Dialog, which cannot be dismissed by clicking outside.
  • Don’t put long forms in a dialog. Use a page or a Sheet.

Accessibility

  • Renders role="dialog" with aria-modal. Dialog.Title names it and Dialog.Description describes it, so always include a title.
  • Focus moves into the dialog on open, stays trapped inside and goes back to the trigger on close.
  • Escape and a click on the scrim close it. Pass interactOutsideBehavior="ignore" to Dialog.Content to keep it open.
  • The corner close button has the label "Close" for screen readers.
  • Content behind the dialog is inert and page scroll is locked while it is open.

API reference

Dialog.Root

Holds the open state. Renders no element.

PropTypeDefault
open bindboolean

Whether the dialog is open.

false
onOpenChange (open: boolean) => void

Called when the dialog opens or closes.

–
onOpenChangeComplete (open: boolean) => void

Called after the open or close animation ends.

–

Dialog.Trigger

renders <button> and accepts its attributes

Opens the dialog. Use the child snippet to render a Button.

PropTypeDefault
child Snippet<[{ props }]>

Render your own element and spread props onto it.

–
Data attributeMeaning
data-state"open" or "closed".

Dialog.Content

renders <div> and accepts its attributes

The card. Renders the portal and the scrim (Dialog.Overlay) for you.

PropTypeDefault
size 'sm' | 'md' | 'lg'

Maximum width from 640px up: 400, 560 or 720px.

'md'
showCloseButton boolean

Shows a ghost icon button in the top right corner.

true
interactOutsideBehavior 'close' | 'ignore' | 'defer-otherwise-close' | 'defer-otherwise-ignore'

What a click on the scrim does.

'close'
escapeKeydownBehavior 'close' | 'ignore' | 'defer-otherwise-close' | 'defer-otherwise-ignore'

What Escape does.

'close'
onOpenAutoFocus (event: Event) => void

Call event.preventDefault() to move focus yourself.

–
portalProps Dialog.PortalProps

Props for the portal, for example to, to render somewhere else.

–
ref bindHTMLDivElement | null

The content element.

–
class ClassValue

Merged with the card classes.

–
Data attributeMeaning
data-slot="dialog-content"Always present.
data-sizeThe current size.
data-state"open" or "closed", drives the animation.

Dialog.Header

renders <div> and accepts its attributes

Stacks eyebrow, title and description. Leaves room for the close button on the right.

PropTypeDefault
class ClassValue

Merged with the defaults.

–

Dialog.Eyebrow

renders <span> and accepts its attributes

Statix addition. A grey chip above the title for context, such as "Backup from yesterday, 22:05".

PropTypeDefault
class ClassValue

Merged with the defaults.

–

Dialog.Title

renders <div role="heading"> and accepts its attributes

Names the dialog. 24px, semibold, balanced line breaks.

PropTypeDefault
level 1 | 2 | 3 | 4 | 5 | 6

Heading level.

2

Dialog.Description

renders <div> and accepts its attributes

Describes the dialog for screen readers. 15px in ink-2.

Dialog.Footer

renders <div> and accepts its attributes

Buttons, right-aligned from 640px up. On phones they stack with the primary on top.

PropTypeDefault
showCloseButton boolean

Adds a ghost "Close" button before the children.

false

Dialog.Close

renders <button> and accepts its attributes

Closes the dialog. Use the child snippet to render a Button.

Dialog.Overlay

renders <div> and accepts its attributes

The scrim: ink at 40% with a 4px backdrop blur. Dialog.Content renders it, so you only need it in custom layouts.

Data attributeMeaning
data-slot="dialog-overlay"Always present.

dialogContentVariants

The tailwind-variants function behind Dialog.Content.