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
<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.
| Prop | Type | Default |
|---|---|---|
open bind | boolean 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 attributesOpens the dialog. Use the child snippet to render a Button.
| Prop | Type | Default |
|---|---|---|
child | Snippet<[{ props }]> Render your own element and spread props onto it. | – |
| Data attribute | Meaning |
|---|---|
data-state | "open" or "closed". |
Dialog.Content
renders<div> and accepts its attributesThe card. Renders the portal and the scrim (Dialog.Overlay) for you.
| Prop | Type | Default |
|---|---|---|
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 bind | HTMLDivElement | null The content element. | – |
class | ClassValue Merged with the card classes. | – |
| Data attribute | Meaning |
|---|---|
data-slot="dialog-content" | Always present. |
data-size | The current size. |
data-state | "open" or "closed", drives the animation. |
Dialog.Header
renders<div> and accepts its attributesStacks eyebrow, title and description. Leaves room for the close button on the right.
| Prop | Type | Default |
|---|---|---|
class | ClassValue Merged with the defaults. | – |
Dialog.Eyebrow
renders<span> and accepts its attributesStatix addition. A grey chip above the title for context, such as "Backup from yesterday, 22:05".
| Prop | Type | Default |
|---|---|---|
class | ClassValue Merged with the defaults. | – |
Dialog.Title
renders<div role="heading"> and accepts its attributesNames the dialog. 24px, semibold, balanced line breaks.
| Prop | Type | Default |
|---|---|---|
level | 1 | 2 | 3 | 4 | 5 | 6 Heading level. | 2 |
Dialog.Description
renders<div> and accepts its attributesDescribes the dialog for screen readers. 15px in ink-2.
Dialog.Footer
renders<div> and accepts its attributesButtons, right-aligned from 640px up. On phones they stack with the primary on top.
| Prop | Type | Default |
|---|---|---|
showCloseButton | boolean Adds a ghost "Close" button before the children. | false |
Dialog.Close
renders<button> and accepts its attributesCloses the dialog. Use the child snippet to render a Button.
Dialog.Overlay
renders<div> and accepts its attributesThe scrim: ink at 40% with a 4px backdrop blur. Dialog.Content renders it, so you only need it in custom layouts.
| Data attribute | Meaning |
|---|---|
data-slot="dialog-overlay" | Always present. |
dialogContentVariants
The tailwind-variants function behind Dialog.Content.