Open a focused task over the page.
A dialog gives a task its own space: share a link, edit a record, or collect a few details. It manages focus, Escape, outside presses, and returning to where you started.
<script lang="ts">
import { XIcon } from "@lucide/svelte"
import {
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
import { Field, FieldLabel } from "@ui-sdk/svelte/field"
import { Input } from "@ui-sdk/svelte/input"
</script>
<Dialog>
<DialogTrigger>Share</DialogTrigger>
<DialogBackdrop />
<DialogContent>
<div data-slot="stack">
<DialogTitle>Share link</DialogTitle>
<DialogDescription
>Anyone who has this link will be able to view this.</DialogDescription
>
</div>
<Field>
<FieldLabel>Link</FieldLabel>
<Input defaultValue="https://example.com/project" readonly />
</Field>
<div data-slot="row">
<DialogClose data-variant="solid">Done</DialogClose>
</div>
<DialogClose aria-label="Close">
<XIcon aria-hidden="true" />
</DialogClose>
</DialogContent>
</Dialog>Installation
npm install @ui-sdk/svelte @ui-sdk/coreComposition
Use the following composition to build a Dialog:
Dialog
├── DialogTrigger
├── DialogBackdrop
└── DialogContent
├── DialogTitle
├── DialogDescription
└── DialogCloseThe title names the dialog; the description gives it context. A dialog can have several Close parts. Give an icon-only close button an accessible name, as the first example does.
The backdrop is optional. Without one, style the content’s ::backdrop. For a question that requires an explicit answer, use Alert Dialog.
Usage
Import the parts and put them together:
<script lang="ts">
import {
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
</script>
<Dialog>
<DialogTrigger>Open</DialogTrigger>
<DialogBackdrop />
<DialogContent>
<DialogTitle>Project details</DialogTitle>
<DialogDescription>Review the details before continuing.</DialogDescription>
<DialogClose>Close</DialogClose>
</DialogContent>
</Dialog>Build Your Own
@ui-sdk/svelte/dialog comes with a ready-made Dialog. If you'd like to build your own, with your own names, start from the dialog primitive in @ui-sdk/core:
import { dialog } from "@ui-sdk/core/dialog"
import { createParts } from "@ui-sdk/svelte/primitive"
const {
Root: Share,
Trigger: ShareTrigger,
Backdrop: ShareBackdrop,
Content: SharePanel,
Title: ShareTitle,
Description: ShareDescription,
Close: ShareClose,
} = createParts(dialog, {
trigger: "button",
backdrop: "div",
content: "div",
title: "h2",
description: "p",
close: "button",
})
export {
Share,
ShareBackdrop,
ShareClose,
ShareDescription,
SharePanel,
ShareTitle,
ShareTrigger,
}<Share>
<ShareTrigger>Share</ShareTrigger>
<ShareBackdrop />
<SharePanel>
<ShareTitle>Share this page</ShareTitle>
<ShareDescription>Anyone with the link can view it.</ShareDescription>
<ShareClose>Done</ShareClose>
</SharePanel>
</Share>Each part keeps the behavior, state and data attributes of its ready-made counterpart: the content opens in the top layer, traps focus and makes the page inert. See Rendering and Custom Parts for more.
Scrollable Content
Keep the header and actions outside the scrolling area. A viewport height limit, a shrinking middle grid row, and overflow-y: auto keep long content usable. initialFocus="content" focuses the dialog itself so reading starts at the top.
<script lang="ts">
import {
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
const paragraphs = [
"These terms govern your use of the service. By creating an account, you agree to them and to the privacy policy that explains how we handle your data.",
"You're responsible for the content you upload and for keeping your password safe. Tell us right away if you think someone else has used your account.",
"We may change the service, and these terms, as the product grows. When a change affects you, we'll let you know by email at least 30 days before it takes effect.",
"You can stop using the service at any time. We'll keep your data for 30 days after you close your account, so you can export it, and then delete it.",
"The service is provided as is. To the extent the law allows, we aren't liable for indirect damages, lost profits or lost data.",
"If you have questions about these terms, write to us. We read every message and reply within two working days.",
]
</script>
<Dialog>
<DialogTrigger>Scrollable Content</DialogTrigger>
<DialogBackdrop />
<DialogContent initialFocus="content">
<div data-slot="stack">
<DialogTitle>Terms of service</DialogTitle>
<DialogDescription>Please read before you continue.</DialogDescription>
</div>
<div data-slot="scroll">
{#each paragraphs as paragraph (paragraph)}
<p>{paragraph}</p>
{/each}
</div>
<div data-slot="row">
<DialogClose>Decline</DialogClose>
<DialogClose data-variant="solid" value="accept">Accept</DialogClose>
</div>
</DialogContent>
</Dialog>Forms
A form with method="dialog" closes the dialog on a valid submission. The submit button’s value becomes the returnValue, just like a Close part’s value. An ordinary form stays open until you close the dialog yourself.
<script lang="ts">
import {
Dialog,
DialogBackdrop,
DialogContent,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
import { Field, FieldLabel } from "@ui-sdk/svelte/field"
import { Input } from "@ui-sdk/svelte/input"
import { useLog } from "./log"
const log = useLog()
</script>
<Dialog
onOpenChange={(open, details) => {
if (!open) {
log(
details.returnValue
? `Saved as ${details.returnValue}`
: `Closed (${details.reason})`
)
}
}}
>
<DialogTrigger>New Article</DialogTrigger>
<DialogBackdrop />
<DialogContent>
<div data-slot="stack">
<DialogTitle>New article</DialogTitle>
<DialogDescription
>Save it as a draft or publish it now.</DialogDescription
>
</div>
<form data-slot="stack" method="dialog">
<Field>
<FieldLabel>Title</FieldLabel>
<Input required defaultValue="Shipping updates for spring" />
</Field>
<div data-slot="row">
<button type="submit" value="draft">Save Draft</button>
<button data-variant="solid" type="submit" value="published"
>Publish</button
>
</div>
</form>
</DialogContent>
</Dialog>Focus
Use initialFocus to pick where focus starts, and finalFocus to choose where it goes after closing. Each takes a selector, an element or a function returning one. The default returns to the trigger, or to the element focused before a controller opened the dialog. See popup focus for the shared focus rules.
<DialogContent initialFocus="#invite-email" finalFocus={() => nextStep} />Controlled
Use bind:open to keep the dialog's state in your component. Cancel a proposed change with details.cancel() in onOpenChange. onOpenChangeComplete reports when opening or closing has finished; see state and events for the common change contract.
<script lang="ts">
import { CheckIcon } from "@lucide/svelte"
import { Checkbox, CheckboxIndicator } from "@ui-sdk/svelte/checkbox"
import {
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
import { useLog } from "./log"
const topics = [
{ label: "Product updates", checked: true },
{ label: "Security alerts", checked: true },
{ label: "Weekly digest", checked: false },
]
const log = useLog()
let open = $state(false)
</script>
<div data-slot="stack">
<div data-slot="controls">
<label data-slot="label">
<Checkbox
checked={open}
onCheckedChange={(next) => (open = next === true)}
>
<CheckboxIndicator>
<CheckIcon aria-hidden="true" />
</CheckboxIndicator>
</Checkbox>
Open
</label>
</div>
<Dialog
bind:open
onOpenChange={(next, details) =>
log(`${next ? "Opened" : "Closed"} (${details.reason})`)}
onOpenChangeComplete={(next) =>
log(next ? "Finished opening" : "Finished closing")}
>
<DialogTrigger>Notification Settings</DialogTrigger>
<DialogBackdrop />
<DialogContent>
<div data-slot="stack">
<DialogTitle>Notification settings</DialogTitle>
<DialogDescription>Choose what we email you about.</DialogDescription>
</div>
<div data-slot="stack">
{#each topics as topic (topic.label)}
<label data-slot="label">
<Checkbox defaultChecked={topic.checked}>
<CheckboxIndicator>
<CheckIcon aria-hidden="true" />
</CheckboxIndicator>
</Checkbox>
{topic.label}
</label>
{/each}
</div>
<div data-slot="row">
<DialogClose data-variant="solid">Done</DialogClose>
</div>
</DialogContent>
</Dialog>
</div>Keyboard Shortcut
A trigger’s shortcut opens it from the keyboard. mod+j means Command+J on Apple platforms and Control+J elsewhere. The Shortcut part displays the right keys and the trigger exposes aria-keyshortcuts.
<script lang="ts">
import { PlusIcon } from "@lucide/svelte"
import {
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogShortcut,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
import { Field, FieldLabel } from "@ui-sdk/svelte/field"
import { Input } from "@ui-sdk/svelte/input"
</script>
<Dialog>
<DialogTrigger shortcut="mod+j">
<PlusIcon aria-hidden="true" />
New Contact
<DialogShortcut />
</DialogTrigger>
<DialogBackdrop />
<DialogContent>
<div data-slot="stack">
<DialogTitle>New contact</DialogTitle>
<DialogDescription>Add someone to your address book.</DialogDescription>
</div>
<form data-slot="stack" method="dialog">
<Field>
<FieldLabel>Name</FieldLabel>
<Input name="name" required placeholder="Kofi Mensah" />
</Field>
<Field>
<FieldLabel>Email</FieldLabel>
<Input
name="email"
type="email"
required
placeholder="kofi@example.com"
/>
</Field>
<div data-slot="row">
<DialogClose>Cancel</DialogClose>
<button data-variant="solid" type="submit" value="save"
>Save Contact</button
>
</div>
</form>
</DialogContent>
</Dialog>Animation
The content and backdrop have data-starting-style while they open and data-ending-style while they close. Transition from those states, and the dialog stays mounted until the exit finishes. onOpenChangeComplete runs after the transition, and keepMounted keeps the content in the page while closed.
[data-slot="dialog-content"] {
transition:
opacity 0.2s,
translate 0.25s cubic-bezier(0.22, 1, 0.36, 1),
scale 0.25s cubic-bezier(0.22, 1, 0.36, 1);
&:is([data-starting-style], [data-ending-style]) {
opacity: 0;
translate: 0 16px;
scale: 0.96;
}
&[data-ending-style] {
transition-duration: 0.15s;
}
}<script lang="ts">
import {
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
import { useLog } from "./log"
const log = useLog()
</script>
<Dialog
onOpenChangeComplete={(open) =>
log(open ? "Finished opening" : "Finished closing")}
>
<DialogTrigger>Slide In</DialogTrigger>
<DialogBackdrop />
<DialogContent keepMounted>
<div data-slot="stack">
<DialogTitle>Slide and fade</DialogTitle>
<DialogDescription
>300ms in and out. Focus returns as soon as it starts closing.</DialogDescription
>
</div>
<div data-slot="row">
<DialogClose data-variant="solid">Close</DialogClose>
</div>
</DialogContent>
</Dialog>Modal
modal controls how the dialog shares the page:
true, the default, makes the page inert, locks scrolling, and keeps Tab inside."trap-focus"keeps Tab inside while the page can still scroll and receive clicks. A click on the page also closes the dialog, unlesscloseOnOutsidePressis false.falseputs the dialog beside the page and lets focus leave it. Escape closes it while focus is inside; outside presses close it only whencloseOnOutsidePressis enabled.
To keep a small part of the page usable while a modal dialog is open, like a chat launcher, pass it to persistentElements: an array of elements or selectors, or a function returning elements when the dialog opens. Persistent elements don't change stacking on their own.
Dialogs render where you put them and use the browser's top layer. Set container when their DOM needs to live elsewhere, like a shadow root. The popup guide covers containers and iframes.
<script lang="ts">
import { CheckIcon, ChevronDownIcon } from "@lucide/svelte"
import { Checkbox, CheckboxIndicator } from "@ui-sdk/svelte/checkbox"
import {
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
import {
Select,
SelectContent,
SelectItem,
SelectItemIndicator,
SelectLabel,
SelectTrigger,
SelectValue,
} from "@ui-sdk/svelte/select"
const modes = [
{ value: "true", label: "Modal" },
{ value: "trap-focus", label: "Trap focus" },
{ value: "false", label: "Non-modal" },
]
type Mode = "true" | "trap-focus" | "false"
const notes = {
true: "The rest of the page is inert and doesn't scroll.",
"trap-focus":
"Tab stays inside, and the page still scrolls and takes clicks.",
false:
"The page stays usable. Tab leaves the notes, and Escape closes them while focus is inside.",
}
let mode = $state<Mode>("false")
let outside = $state(false)
const modal = $derived(
mode === "true" ? true : mode === "false" ? false : "trap-focus"
)
</script>
<div data-slot="stack">
<div data-slot="controls">
<Select
items={modes}
value={mode}
onValueChange={(next) => next && (mode = next as Mode)}
>
<SelectLabel>Modal</SelectLabel>
<SelectTrigger>
<SelectValue />
<ChevronDownIcon />
</SelectTrigger>
<SelectContent>
{#each modes as option (option.value)}
<SelectItem value={option.value}>
{option.label}
<SelectItemIndicator>
<CheckIcon />
</SelectItemIndicator>
</SelectItem>
{/each}
</SelectContent>
</Select>
<label data-slot="label">
<Checkbox
checked={outside}
onCheckedChange={(next) => (outside = next === true)}
>
<CheckboxIndicator>
<CheckIcon aria-hidden="true" />
</CheckboxIndicator>
</Checkbox>
Close on outside press
</label>
</div>
<Dialog {modal} closeOnOutsidePress={outside}>
<DialogTrigger>Open Notes</DialogTrigger>
{#if modal === true}
<DialogBackdrop />
{/if}
<DialogContent>
<div data-slot="stack">
<DialogTitle>Notes</DialogTitle>
<DialogDescription>{notes[mode]}</DialogDescription>
</div>
<textarea aria-label="Notes" value="Call the printer about the proofs."
></textarea>
<div data-slot="row">
<DialogClose data-variant="solid">Done</DialogClose>
</div>
</DialogContent>
</Dialog>
</div>Warn Before Closing a Dirty Form
Set dismissible to false while there are unsaved changes. Escape, an outside press, or a back gesture then keeps the dialog open and reports onDismissAttempt. Explicit Close parts and controller calls still work, so you can offer a deliberate way out.
<script lang="ts">
import {
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
import { Field, FieldControl, FieldLabel } from "@ui-sdk/svelte/field"
let open = $state(false)
let dirty = $state(false)
let asking = $state(false)
let post: HTMLTextAreaElement | undefined = $state()
function close() {
open = false
dirty = false
asking = false
}
function keepEditing() {
asking = false
post?.focus()
}
</script>
<Dialog
bind:open={() => open, (next) => (next ? (open = true) : close())}
dismissible={!dirty}
onDismissAttempt={() => (asking = true)}
>
<DialogTrigger>Write a Post</DialogTrigger>
<DialogBackdrop />
<DialogContent>
<div data-slot="stack">
<DialogTitle>New post</DialogTitle>
<DialogDescription>Share an update with your team.</DialogDescription>
</div>
<Field>
<FieldLabel>Post</FieldLabel>
<FieldControl
oninput={(event) => (dirty = event.currentTarget.value !== "")}
>
{#snippet render({ props })}
<textarea bind:this={post} {...props} placeholder="What's new?"
></textarea>
{/snippet}
</FieldControl>
</Field>
{#if asking}
<div data-slot="row" role="alert">
Discard your changes?
<div data-slot="row">
<button type="button" onclick={keepEditing}>Keep Editing</button>
<button data-variant="solid" type="button" onclick={close}
>Discard</button
>
</div>
</div>
{:else}
<div data-slot="row">
<DialogClose data-variant="solid" value="post">Post</DialogClose>
</div>
{/if}
</DialogContent>
</Dialog>Nested Dialogs
A dialog opened inside another joins its stack. Escape closes the topmost dialog and returns focus to its trigger. Closing the parent also closes its children. data-nested-open and --dialog-stack let you show which layer is active.
<script lang="ts">
import {
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
import { Field, FieldLabel } from "@ui-sdk/svelte/field"
import { Input } from "@ui-sdk/svelte/input"
</script>
<Dialog>
<DialogTrigger>Account</DialogTrigger>
<DialogBackdrop />
<DialogContent>
<div data-slot="stack">
<DialogTitle>Account</DialogTitle>
<DialogDescription>Manage how you sign in.</DialogDescription>
</div>
<div data-slot="card">
<div data-slot="stack">
<span>Password</span>
<span data-slot="hint">Last changed 3 months ago</span>
</div>
<Dialog>
<DialogTrigger>Change Password</DialogTrigger>
<DialogBackdrop />
<DialogContent>
<div data-slot="stack">
<DialogTitle>Change password</DialogTitle>
<DialogDescription>Use at least 12 characters.</DialogDescription>
</div>
<Field>
<FieldLabel>New password</FieldLabel>
<Input type="password" />
</Field>
<div data-slot="row">
<DialogClose>Cancel</DialogClose>
<DialogClose data-variant="solid">Update</DialogClose>
</div>
</DialogContent>
</Dialog>
</div>
<div data-slot="row">
<DialogClose data-variant="solid">Done</DialogClose>
</div>
</DialogContent>
</Dialog>Opening from a Menu Item
Render the dialog outside the menu and open it with the dialog’s controller. When the item disappears, the menu’s trigger becomes the place to return focus.
<script lang="ts">
import { CopyIcon, EllipsisIcon, PencilIcon } from "@lucide/svelte"
import {
createDialogController,
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogTitle,
} from "@ui-sdk/svelte/dialog"
import { Field, FieldLabel } from "@ui-sdk/svelte/field"
import { Input } from "@ui-sdk/svelte/input"
import { Menu, MenuContent, MenuItem, MenuTrigger } from "@ui-sdk/svelte/menu"
const rename = createDialogController()
</script>
<Menu>
<MenuTrigger aria-label="File actions">
<EllipsisIcon aria-hidden="true" />
</MenuTrigger>
<MenuContent>
<MenuItem onSelect={() => rename.open()}>
<PencilIcon aria-hidden="true" />
Rename…
</MenuItem>
<MenuItem>
<CopyIcon aria-hidden="true" />
Duplicate
</MenuItem>
</MenuContent>
</Menu>
<Dialog controller={rename}>
<DialogBackdrop />
<DialogContent>
<div data-slot="stack">
<DialogTitle>Rename file</DialogTitle>
<DialogDescription>Names must be unique in a folder.</DialogDescription>
</div>
<Field>
<FieldLabel>Name</FieldLabel>
<Input defaultValue="report.pdf" />
</Field>
<div data-slot="row">
<DialogClose>Cancel</DialogClose>
<DialogClose data-variant="solid" value="rename">Rename</DialogClose>
</div>
</DialogContent>
</Dialog>Opening from Anywhere
Connect several triggers to one createDialogController<Payload, Result>(). Each trigger passes a payload; the content's children snippet reads it from state.payload, typed with DialogContentState<Payload>. controller.open({ payload }) opens it from code and returns a promise that resolves when it closes, with the reason and any returnValue. Each trigger remains the return-focus target for the dialog it opened. See controllers for the shared controller pattern.
<script lang="ts">
import {
createDialogController,
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
type DialogContentState,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
import { useLog } from "./log"
type Invoice = {
id: string
customer: string
amount: string
status: "Paid" | "Due"
}
const invoices: Invoice[] = [
{ id: "INV-001", customer: "Acme", amount: "$250.00", status: "Paid" },
{ id: "INV-002", customer: "Globex", amount: "$150.00", status: "Due" },
{ id: "INV-003", customer: "Initech", amount: "$350.00", status: "Due" },
]
const reminder = createDialogController<Invoice, "send">()
const log = useLog()
async function remindFromCode() {
const { reason, returnValue } = await reminder.open({
payload: invoices[2],
})
log(
returnValue === "send" ? "Reminder sent from code" : `Closed (${reason})`
)
}
</script>
<div data-slot="stack">
<div data-slot="controls">
<button type="button" onclick={remindFromCode}>Open from Code</button>
</div>
<ul data-slot="list">
{#each invoices as invoice (invoice.id)}
<li data-slot="row">
{invoice.customer}
<span data-slot="hint">{invoice.amount} · {invoice.status}</span>
<DialogTrigger
controller={reminder}
payload={invoice}
disabled={invoice.status === "Paid"}
aria-label={`Remind ${invoice.customer}`}
>
Remind
</DialogTrigger>
</li>
{/each}
</ul>
<Dialog
controller={reminder}
onOpenChange={(open, details) => {
if (!open && details.returnValue === "send") {
log("Reminder sent")
}
}}
>
<DialogBackdrop />
<DialogContent>
{#snippet children(state: DialogContentState<Invoice>)}
<div data-slot="stack">
<DialogTitle>Remind {state.payload?.customer}</DialogTitle>
<DialogDescription>
{state.payload?.id} for {state.payload?.amount} is due. We'll email the
billing contact.
</DialogDescription>
</div>
<div data-slot="row">
<DialogClose>Cancel</DialogClose>
<DialogClose data-variant="solid" value="send"
>Send reminder</DialogClose
>
</div>
{/snippet}
</DialogContent>
</Dialog>
</div>Presentation
presentation="sheet" presents the same task as a sheet. Use "auto" to choose a sheet on small touch screens and a centered dialog elsewhere, decided each time it opens. A swipe down closes a dismissible sheet; a protected one springs back and reports a dismissal attempt.
Style data-presentation to support both layouts. The sheet manages its own position and movement, so do not apply the centered dialog’s translation to it. --sheet-backdrop styles the dimmed page when no Backdrop part is present.
<script lang="ts">
import {
Dialog,
DialogClose,
DialogContent,
DialogDescription,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
import { Field, FieldLabel } from "@ui-sdk/svelte/field"
import { Input } from "@ui-sdk/svelte/input"
</script>
<Dialog presentation="sheet">
<DialogTrigger>Edit Profile</DialogTrigger>
<DialogContent>
<div data-slot="stack">
<DialogTitle>Edit profile</DialogTitle>
<DialogDescription
>Make changes to your profile here. Save when you're done.</DialogDescription
>
</div>
<Field>
<FieldLabel>Name</FieldLabel>
<Input defaultValue="Hollis Grant" />
</Field>
<Field>
<FieldLabel>Username</FieldLabel>
<Input defaultValue="@hollis" />
</Field>
<div data-slot="row">
<DialogClose>Cancel</DialogClose>
<DialogClose data-variant="solid" value="save">Save Changes</DialogClose>
</div>
</DialogContent>
</Dialog>Custom Rendering
Every part takes a render snippet, which receives the props to spread and the part's state, and the children snippet receives the state too.
<script lang="ts">
import {
Dialog,
DialogBackdrop,
DialogClose,
DialogContent,
DialogDescription,
DialogShortcut,
DialogTitle,
DialogTrigger,
} from "@ui-sdk/svelte/dialog"
</script>
<Dialog>
<DialogTrigger shortcut="mod+i">
{#snippet render({ props, state })}
<button {...props}>
{state.open ? "Viewing" : "View Details"}
<DialogShortcut>
{#snippet children(shortcut)}{shortcut.text}{/snippet}
</DialogShortcut>
</button>
{/snippet}
</DialogTrigger>
<DialogBackdrop />
<DialogContent>
{#snippet children(state)}
<div data-slot="stack">
<DialogTitle>
{#snippet render({ props })}
<h3 {...props}>Details</h3>
{/snippet}
</DialogTitle>
<DialogDescription>
{state.nested
? "Opened from another dialog."
: "Quarterly report, updated today."}
</DialogDescription>
</div>
<div data-slot="row">
<DialogClose>Close</DialogClose>
<DialogClose data-variant="solid" href="https://example.com/details">
{#snippet render({ props })}
<a {...props}>Open the Full Page</a>
{/snippet}
</DialogClose>
</div>
{/snippet}
</DialogContent>
</Dialog>Styling
Each part has a data-slot, such as dialog-content, and shows its state through the attributes listed under Data Attributes. Use data-open and data-closed for each state, and data-starting-style and data-ending-style for transitions.
DialogContent
| Variable | What it holds |
|---|---|
--dialog-stack | How many dialogs are open above this one, nested inside it. 0 for the topmost. |
--keyboard-inset | Unless it presents as a sheet: how many pixels of the page the on-screen keyboard covers, 0 without one. |
--visual-viewport-width | Unless it presents as a sheet: the width of the part of the page you can see. |
--visual-viewport-height | Unless it presents as a sheet: the height of the part of the page you can see, above the keyboard. |
--visual-viewport-top | Unless it presents as a sheet: how far the part of the page you can see is scrolled from the top of the layout, as when the keyboard pushes it up. |
--drawer-progress | While it presents as a sheet: how far open the sheet is, from 0 closed to 1 at its largest snap point. Never past 1. |
--drawer-dim | While it presents as a sheet: how dim the page behind is, from 0 to 1. The backdrop's opacity follows it. |
--drawer-expand | While it presents as a sheet: 0 at the second-largest snap point and below, 1 at the largest. With one snap point, the whole travel. |
--drawer-stack | While it presents as a sheet: how many sheets opened from inside this one are open above it, rising smoothly as each one opens. Push it back with it. |
--sheet-backdrop | Set it yourself: the color the page dims to while it presents as a sheet. Black at 0.2 by default. |
Viewport
| Variable | What it holds |
|---|---|
--keyboard-inset | While it presents as a sheet: how many pixels of the page the on-screen keyboard covers, 0 without one. |
--visual-viewport-width | While it presents as a sheet: the width of the part of the page you can see. |
--visual-viewport-height | While it presents as a sheet: the height of the part of the page you can see, above the keyboard. |
--visual-viewport-top | While it presents as a sheet: how far the part of the page you can see is scrolled from the top of the layout, as when the keyboard pushes it up. |
Data Attributes
DialogTrigger
[data-slot="dialog-trigger"]
| Attribute | What it means |
|---|---|
data-closed | Present while the dialog is closed, including while it animates out. |
data-disabled | Present when the trigger is disabled. |
data-open | Present while the dialog is open. On a trigger, while it's open from that trigger. |
DialogBackdrop
[data-slot="dialog-backdrop"]
| Attribute | What it means |
|---|---|
data-closed | Present while the dialog is closed, including while it animates out. |
data-open | Present while the dialog is open. On a trigger, while it's open from that trigger. |
data-starting-style | Present for the first frame. Style the state you animate from. |
data-ending-style | Present while the dialog animates out. Style the state you animate to. |
DialogContent
[data-slot="dialog-content"]
| Attribute | What it means |
|---|---|
data-closed | Present while the dialog is closed, including while it animates out. |
data-presentation | dialogsheetHow the dialog presents this time it's open. |
data-open | Present while the dialog is open. On a trigger, while it's open from that trigger. |
data-starting-style | Present for the first frame. Style the state you animate from. |
data-ending-style | Present while the dialog animates out. Style the state you animate to. |
data-keyboard | Present while the on-screen keyboard covers part of the page. |
DialogClose
[data-slot="dialog-close"]
| Attribute | What it means |
|---|---|
data-pending | Present on a Close part while its action runs. |
API Reference
Props and callbacks are the same as below, as Svelte props. open can be bound with bind:open.
Dialog
container?DocumentFragment | Element | null- Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
open?boolean- Whether the dialog is open. Pass it to control the dialog.
defaultOpen?boolean- Whether the dialog starts open, when uncontrolled. Focus moves into it once it's on the page.
onOpenChangeComplete?((open: boolean) => void)- Runs once the dialog has finished opening or closing, after any animation.
dismissible?boolean- Whether Escape, an outside press and Android's back gesture can close the dialog. Close parts, triggers and the controller always can. Pass
falsewhile a form has unsaved changes, and ask inonDismissAttempt. onDismissAttempt?((details: DialogDismissAttemptDetails) => void)- Runs when a dismissal was refused, because
dismissibleis false, an outside press doesn't close it, or a Close part's action is running. Ask "Discard changes?" here. persistentElements?(string | Element)[] | (() => Element[])- Elements that stay usable while the dialog makes the page inert, like a chat launcher or a password manager's button. Elements, CSS selectors, or a function that returns elements, read when the dialog opens. Presses on them never close it.
pendingAnnouncement?string- What screen readers hear once a Close part's action has been running for a second, so a slow action doesn't pass in silence. Set it in the page's language. An empty string says nothing.
debug?boolean- Logs every state change with its reason to the console, in development builds.
onOpenChange?((open: boolean, details: DialogOpenChangeDetails) => void)- Runs when the dialog wants to open or close.
details.reasonsays why,details.cancel()stops it, anddetails.returnValuecarries what closed it. onPayloadChange?((payload: unknown, details: ChangeDetails<DialogPayloadChangeReason>) => void)- Runs when the payload the content shows changes: a trigger with another payload opens the dialog, or takes a non-modal dialog over while it's open, which fires no
onOpenChange, and so does a controller'sopen({ payload })on the open dialog.details.cancel()keeps the previous payload. modal?"trap-focus" | booleantrue: the rest of the page is inert and doesn't scroll, focus is trapped, and an outside press only closes the dialog."trap-focus": traps focus, and leaves the page scrollable and clickable.false: a dialog beside the page, which Tab can leave and outside presses don't close.closeOnOutsidePress?boolean- Whether pressing outside the dialog, like on its backdrop, closes it. The press counts once it's released outside too, so dragging a text selection out of a field doesn't close it.
presentation?PresentationSetting<"dialog">- How the dialog presents.
"sheet"slides it up from the bottom of the screen, where it can be swiped away, and"auto"does that on small touch screens. Decided each time it opens; the server renders"dialog"for"auto". controller?PopupController<any, DialogOpenChangeReason, {}, any, DialogPayloadChangeReason>- Opens, closes and inspects the dialog from anywhere, and connects triggers outside it. Create one with
createDialogController().
DialogTrigger
A trigger outside the dialog also takes controller.
disabled?boolean- Stops the trigger from opening the dialog. A native button can't be focused or pressed, unless
focusableWhenDisabledis set. focusableWhenDisabled?boolean- Keeps a disabled trigger in the tab order with
aria-disabledinstead of the native attribute, so it can host a tooltip that says why. Presses still do nothing. payload?unknown- Data for the content to render when this trigger opens the dialog, like the row it belongs to.
shortcut?string- A keyboard shortcut that presses the trigger, like
"mod+k".modis Command on Apple platforms and Control elsewhere. Setsaria-keyshortcuts, and a Shortcut part inside shows it. A modal dialog pauses the page's shortcuts while it's open. controller?PopupController<any, DialogOpenChangeReason, {}, any, DialogPayloadChangeReason>- Connects a trigger outside the dialog, like one per table row, to the dialog with this controller.
DialogBackdrop
Dims the page behind a modal dialog. Renders a div.
DialogContent
container?DocumentFragment | Element | null- Renders the popup into this element instead of in place, like a container inside a shadow root or an iframe. On web components, a CSS selector. Nested popups stay inside their parent.
initialFocus?DialogInitialFocus- Where focus goes when the dialog opens. Opening with touch focuses the dialog itself, so no on-screen keyboard appears.
finalFocus?PopupFocusTarget- Where focus goes when the dialog closes while focus is inside it.
keepMounted?boolean- Whether the dialog stays in the page, hidden, while closed. For animation libraries that drive the exit from state.
DialogTitle
Names the dialog. Renders an h2.
DialogDescription
Describes the dialog while it's rendered. Renders a p.
DialogClose
Its action receives the event and { source }, how the part was pressed, as Button describes.
value?string- Reported as
returnValueinonOpenChangeand by the controller'sopen().createConfirm()resolvestruefor"confirm". action?((event: Event | undefined, details: ActionDetails) => unknown)- Runs when the part is pressed, before the dialog closes. A returned Promise keeps the dialog open while it runs: the part gets
data-pending,aria-busyandaria-disabled, screen readers hear the dialog'spendingAnnouncementafter a second, and nothing but the controller closes the dialog. It closes with reason"action"once the Promise resolves. A rejection keeps it open and puts the reason in the part'serrorstate until the next press, or until the dialog opens again.details.sourcesays how the part was pressed, for changes made after anawait.
DialogShortcut
shortcut?string- The keys to show. Inside a trigger, its
shortcut.
State
What render and children snippets receive, per part.
DialogTrigger:
openboolean- Whether the dialog is open from this trigger.
disabledboolean- Set by the trigger's
disabledprop, which stops it opening the dialog.
DialogBackdrop:
openboolean- Whether the dialog is open. False while it animates out.
nestedboolean- Whether the dialog was opened from inside another dialog.
nestedOpenboolean- Whether a dialog opened from inside this one is open.
DialogContent:
openboolean- Whether the dialog is open. False while it animates out.
modalboolean | "trap-focus"- The
modalsetting. Always true for an alert dialog. nestedboolean- Whether the dialog was opened from inside another dialog.
nestedOpenboolean- Whether a dialog opened from inside this one is open.
stacknumber- How many dialogs are open above this one, nested inside it.
payloadPayload | undefined- The payload of the last open, from the trigger that opened it or a controller, typed as the controller's
Payload. pendingboolean- Whether a Close part's action is running.
presentation"dialog" | "sheet"- How it presents this time it's open.
DialogClose:
pendingboolean- Whether this part's action is running.
errorunknown- Why this part's last action failed, until it's pressed again or the dialog opens again.
DialogShortcut:
textstring- The shortcut formatted for this platform:
⌘Kon Apple platforms andCtrl+Kelsewhere. Empty without one.
Reasons
details.reason says why the dialog opened or closed.
trigger-pressMouseEvent | KeyboardEvent | TouchEvent- Click, tap, Enter or Space on the part that opens, closes or toggles. Arrow keys that open a menu or submenu count too. A tap on a combobox's input that opens a sheet reports its
touchend. close-pressMouseEvent | KeyboardEvent | SubmitEvent- A Close part was pressed, or a form with
method="dialog"was submitted. outside-pressMouseEvent- A press outside the layer.
escape-keyKeyboardEvent- Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
parent-closenone- The parent layer closed.
backEvent- Going back: the Android back button or gesture, or Backspace in an empty command input, which returns to the previous page.
actionMouseEvent | KeyboardEvent- A Close part's
actionfinished. shortcutKeyboardEvent- A keyboard shortcut, like a trigger's
shortcut. swipePointerEvent | TouchEvent- A swipe gesture: a finger, mouse or pen dragged it.
imperativenone- A controller or
apicall, or a property set on a web component.
For a payload change, it says what opened the dialog or took it over.
trigger-pressMouseEvent | KeyboardEvent | TouchEvent- Click, tap, Enter or Space on the part that opens, closes or toggles. Arrow keys that open a menu or submenu count too. A tap on a combobox's input that opens a sheet reports its
touchend. shortcutKeyboardEvent- A keyboard shortcut, like a trigger's
shortcut. imperativenone- A controller or
apicall, or a property set on a web component.
The dismissals dismissible can refuse:
outside-pressMouseEvent- A press outside the layer.
escape-keyKeyboardEvent- Escape, or a submenu's close key (ArrowLeft in left-to-right layouts).
backEvent- Going back: the Android back button or gesture, or Backspace in an empty command input, which returns to the previous page.
swipePointerEvent | TouchEvent- A swipe gesture: a finger, mouse or pen dragged it.
Controller
Create one with createDialogController<Payload, Result>() and pass it as controller, to the dialog and to any
triggers outside it.
Every write method takes an optional { reason, event }, passed to onOpenChange. Closing with a controller always works, even when the dialog isn't dismissible or an action is running.
isOpen()() => boolean- Whether it's open. False as soon as it starts closing, while it still animates out.
setOpen(open, options?)(open: boolean, options?: PopupChangeOptions<DialogOpenChangeReason> | undefined) => boolean- Opens or closes it. Returns false when the change was canceled or it was already open or closed.
open(options?)(options?: (PopupChangeOptions<DialogPayloadChangeReason> & { payload?: Payload | undefined; anchor?: Anchor | undefined; signal?: AbortSignal | undefined; }) | undefined) => Promise<...>- Opens it, and resolves once it closes, with why, how and any return value. Resolves exactly once and never rejects: on the next close from any source, when
signalaborts, or with reason"unmount"when the component leaves the page. close(options?)(options?: (PopupChangeOptions<DialogOpenChangeReason> & { returnValue?: Result | undefined; }) | undefined) => boolean- Closes it.
returnValueis passed to the promiseopen()returned. Returns false when the close was canceled or it was already closed. toggle(options?)(options?: PopupChangeOptions<DialogOpenChangeReason> | undefined) => boolean- Opens it when it's closed, and closes it when it's open. Returns false when the change was canceled.
getPayload()() => Payload | undefined- The payload of the last open, from a controller or the trigger that opened it.
focus()() => void- Moves focus to the trigger that opened it last, or the first trigger.
Events
Callbacks get the new state first, then the details. A bound open only updates when onOpenChange wasn't canceled.
| Prop | On | Receives |
|---|---|---|
bind:open | Dialog | Whether the dialog is open |
onOpenChange | Dialog | (open, details): the new state, the reason and any returnValue |
onOpenChangeComplete | Dialog | (open), after the animation |
onPayloadChange | Dialog | (payload, details): the content's new payload, and the reason |
onDismissAttempt | Dialog | ({ reason, event }), when a dismissal was refused |
Accessibility
The trigger is a button that opens a dialog, and the dialog follows the WAI-ARIA modal dialog pattern: aria-modal while it's modal, labelled by its title, described by its description only while one is rendered. Every line below is an automated test.
Keyboard
| Key | Does |
|---|---|
| Enter, Space | On the trigger, opens the dialog |
| Tab, Shift+Tab | Moves through the dialog's controls, staying inside while it's modal |
| Escape | Closes the topmost dialog and returns focus to its trigger |
| A trigger's shortcut | Opens its dialog from anywhere on the page |
Tested Behavior
- Advertises a dialog.
- Click opens the dialog.
- Enter opens the dialog.
- Space opens the dialog.
- Opening moves focus to the first focusable element.
- Each time focus moves in, the dialog is named by its title and described by its description.
- Tab moves through the dialog in order.
- Tab from the last element wraps to the first.
- Shift+Tab from the first element wraps to the last.
- Shift+Tab from the first element wraps to the checked radio of a group outside a form.
- Tab reaches radios whose group's checked radio is behind the dialog.
- Tab visits a positive tabindex first, like the browser.
- A positive tabindex keeps Tab inside a dialog that leaves the page usable.
- A positive tabindex slotted into a custom element keeps its host's place.
- With a positive tabindex in the dialog, Tab still moves through a shadow root and slots.
- With a positive tabindex in the dialog, Tab from a focused element outside the tab order goes to the next stop.
- Tab from a custom element with a positive tabindex enters its shadow root.
- Opening focuses the first field even when a later one has a positive tabindex.
- Escape closes the dialog and returns focus to the trigger.
- Escape after a click returns focus to the trigger.
- The close button closes the dialog and returns focus to the trigger.
- A virtual click from a screen reader moves focus into the dialog.
- A touch press focuses the dialog itself, so no on-screen keyboard appears.
- Pressing a button inside keeps the dialog open.
- Pressing the backdrop closes the dialog.
- Pressing the backdrop returns focus to the trigger.
- Clicking inside the dialog keeps it open.
- An outside press doesn't reach the page.
- Selecting text in a field and releasing over the backdrop keeps the dialog open.
- Pressing the backdrop and releasing inside the dialog keeps it open.
- A right click on the backdrop keeps the dialog open.
- A dialog styled only with ::backdrop closes when the backdrop is pressed.
- With closeOnOutsidePress false, pressing the backdrop keeps the dialog open.
- Pressing a nested dialog's backdrop closes only the nested dialog.
- While the dialog animates out, a press on its backdrop doesn't reach the page.
- Escape right after opening a nested dialog closes only the nested one.
- Tab never leaves the dialog.
- The page doesn't scroll while the dialog is open.
- The rest of the page is hidden from assistive technology.
- With modal false, the page stays usable.
- Escape closes only the nested dialog and returns focus to its trigger.
- The nested dialog's close button closes only it.
- The outer dialog's open change hears only the outer dialog.
- Tab stays inside the nested dialog.
- A second Escape closes the outer dialog.
Runs in React, Vue and web components.
Additional behaviors:
- Escape while an input method is composing text keeps the dialog open.
- Escape closes a non-modal dialog only while focus is inside it.
- Closing returns focus to the trigger before the exit animation finishes.
- Closing after the trigger is gone moves focus to the element after where it was.
- Closing after the trigger is gone skips past a later positive tabindex.
- A dialog open from the start moves focus inside.
- With initial focus on the content, the dialog itself takes focus.
- The page outside is inert while open and restored exactly after.
- A live region outside the dialog keeps announcing while it's open.
- Tab leaves a non-modal dialog and the dialog stays open.
- A non-modal dialog stays open when the page is clicked.
- A dialog opened inside a dialog marks both, for styling.
- Closing the parent closes the nested dialog with reason parent-close.
- A controller opens the dialog, moves focus in, and resolves with how it closed.
- Aborting the signal closes the dialog, and the promise resolves once.
- A pending open() resolves with reason unmount when the dialog leaves the page. Web components only.
- A form with method dialog closes the dialog and reports the submitter's value.
- A confirm helper resolves true for the action and false otherwise.
- Closing reports why, for every way a dialog closes.
- A trigger connected through a controller shows its shortcut in a Shortcut part, and binds it.
- The open property and attribute open and close the dialog. Web components only.
Runs in React, Vue and web components.
- Choosing the item closes the menu and moves focus into the dialog.
- Choosing the item with the keyboard moves focus into the dialog.
- The page around the dialog is inert, the menu's trigger included.
- Closing the dialog returns focus to the menu's trigger.
- A dialog the item opens through its open prop returns focus to the menu's trigger. React and Vue only.
- A trigger's shortcut opens the dialog.
- The trigger advertises its shortcut, and shows it to sighted users only.
- A modal dialog pauses the page's shortcuts and keeps its own.
- A dialog's own shortcut doesn't run while the dialog is closed.
- Menu and popover triggers take shortcuts too.
- Plain keys typed in a text field are text, and modifier shortcuts still run.
- A plain-key shortcut runs outside text fields.
- Refuses Escape and outside presses, and reports each attempt.
- A clean form closes on Escape.
- Stay usable while a modal dialog is open, and pressing them keeps it open.
- Keep the alert dialog open and pending, then close with reason action.
- A failed action keeps the alert dialog open and stops pending.
- A menu and a dialog inside it render into the popover's container.
- Closes the topmost dialog with reason back.
Runs in React, Vue and web components.
Screen readers hear the same thing in each tested framework, recorded by a virtual screen reader:
- Announcements while using the dialog with a keyboard.
- Announcements while using the alert dialog with a keyboard.
Runs in React, Vue and web components.