Dialog
A modal window (WAI-ARIA dialog pattern): a trigger opens a role="dialog" panel
with aria-modal="true", built on the native <dialog> element and
showModal(): top-layer rendering, an inert background (a real focus trap,
enforced by the browser for keyboard and assistive tech), a stylable
::backdrop, plus body scroll lock.
This is the generic modal the rest of the family builds on. The three presets
are the accessible, stylable equivalents of the platform’s simple dialogs
(alert(), confirm(), prompt()): same headless machinery, same tokens,
differing only in job.
When to use which dialog
Section titled “When to use which dialog”- Dialog — generic modal for any content; the head of the family.
- Alert Dialog — an acknowledgement: a message with nothing to cancel (one button).
- Confirm Dialog — verify or accept before proceeding:
cancel stops, confirm proceeds (
urgentto interrupt). - Prompt Dialog — asks for a single value
(optional,
required, or gated byconfirmValue;urgentto interrupt). - Search Dialog — a quick search: search by keyword and pick from a list.
- Sheet Dialog — a task in an edge-anchored panel
(
sidevariant, optional drag-to-dismiss).
While a dialog is open, the page waits
Section titled “While a dialog is open, the page waits”A modal interrupts by design: showModal() makes everything outside it
inert — non-interactive and silenced for assistive technology too. That
includes floating Notifications:
a toast raised while a dialog is open renders underneath it and is not
announced. This is coherent, not a limitation — background information waits;
anything about the task in progress belongs inside the dialog.
Feedback inside a dialog — for a non-blocking message tied to the task (a failed save, a lost connection), render an Inline Notification in the dialog body. Inside the open dialog it is outside the inert zone, so its live region announces normally:
<Dialog title="Edit profile"> {#if saveError} <InlineNotification status="danger" title="Save failed" role="alert" /> {/if} <form>…</form></Dialog>Dialogs stack — one level, one job. The top layer is a stack: opening a dialog from inside a dialog puts it on top and makes the outer one inert too. The one legitimate case is the confirm-on-close: a Confirm Dialog guarding an edit dialog with unsaved changes. Escape pops one level (the confirm closes, the editor survives, focus returns inside it); scroll stays locked until the last dialog closes. If you need more than one level of stacking, the task wants a different shape, not a deeper stack.
<Dialog title="Edit profile"> <form>…</form> <ConfirmDialog title="Discard changes?" description="Your edits will be lost." confirmLabel="Discard changes" cancelLabel="Keep editing" > Discard </ConfirmDialog></Dialog>Messages while a dialog is open
Section titled “Messages while a dialog is open”A toast above or below a modal dialog is either unseen or in the way. Where a message goes depends on what it is about (ADR 0016):
- About the dialog’s own task: in the dialog. Beside the control that caused it (“Link copied” next to the copy button), or in the dialog’s status area, between the body and the footer (a failed upload with Retry).
- Unrelated, and it can wait: the Notification Region holds it and shows it after the dialog closes.
- Unrelated, and it needs a decision now: a dialog on top, which takes focus and gives it back to the dialog below when it closes.
The custom elements, Svelte, Vue and React implement all three today. Every
dialog in the family has notify(),
dismissNotice(id) and clearNotices(). A notice looks like an Inline
Notification, is announced once through a polite live region, never takes
focus, and is cleared when the dialog closes. notify() on a closed dialog
shows nothing and returns an empty string.
In Svelte the three functions are on the component instance (bind:this),
and copy on Button gives the confirmation beside the control:
<script lang="ts"> import Button from "@invisible-ui/svelte/Button.svelte"; import Dialog from "@invisible-ui/svelte/Dialog.svelte";
let dialog: ReturnType<typeof Dialog> | undefined = $state();
// Called by the application when an upload started in the dialog fails. function onUploadError() { dialog?.notify({ status: "danger", title: "Upload failed", description: "The connection dropped.", action: { label: "Retry", onAction: retryUpload }, }); }</script>
<Dialog bind:this={dialog} title="Share the report"> {#snippet trigger()}Share{/snippet} <Button copy="https://example.com/reports/q3" copiedLabel="Link copied">Copy the link</Button></Dialog>With the custom elements, the methods are on the element, and copy on
<ds-button> gives the confirmation:
<ds-dialog heading="Share the report" trigger="Share"> <ds-button copy="https://example.com/reports/q3" copied-label="Link copied"> Copy the link </ds-button></ds-dialog><script type="module"> const dialog = document.querySelector("ds-dialog"); // Called by the application when an upload started in the dialog fails. function onUploadError() { dialog.notify({ status: "danger", title: "Upload failed", description: "The connection dropped.", action: { label: "Retry", onAction: retryUpload }, }); }</script>In Vue, every dialog in the family exposes the same three methods on its
template ref (type it with DialogNoticeControls), and useDialog returns
them too. copy and copiedLabel on Button give the confirmation beside
the control:
<script setup lang="ts">import { ref } from "vue";import { Button, Dialog, type DialogNoticeControls } from "@invisible-ui/vue";
const share = ref<DialogNoticeControls | null>(null);
const retryUpload = () => { // Start the upload again.};
// Called by the application when an upload started in the dialog fails.function onUploadError() { share.value?.notify({ status: "danger", title: "Upload failed", description: "The connection dropped.", action: { label: "Retry", onAction: retryUpload }, });}</script>
<template> <Dialog ref="share" title="Share the report" trigger="Share"> <Button copy="https://example.com/reports/q3" copied-label="Link copied"> Copy the link </Button> </Dialog></template>In React, a ref on any dialog of the family (type it with DialogHandle)
holds notify(), dismissNotice(id) and clearNotices(), and useDialog(),
useSheetDialog() and useSearchDialog() return them with the notices to
render.
copy on Button gives the confirmation beside the control:
const dialog = useRef<DialogHandle>(null);
// Called by the application when an upload started in the dialog fails.function onUploadError() { dialog.current?.notify({ status: "danger", title: "Upload failed", description: "The connection dropped.", action: { label: "Retry", onAction: retryUpload }, });}
<Dialog ref={dialog} title="Share the report" trigger="Share"> <Button copy="https://example.com/reports/q3" copiedLabel="Link copied"> Copy the link </Button></Dialog>;Live: an edit dialog composing form controls (with their own overlays) and a confirm-on-close, with a tooltip on the trigger.
Multi-step workflows
Section titled “Multi-step workflows”A wizard is a composition of Dialog, not a component of its own. The dialog lends three regions and one body layout; the step number, the form data and the business rules stay in the application.
headerMetaholds the step context above the title, for exampleStep 1 of 2. It is a place to put content, nothing more: it carries no progress role and no live region. Plain text is the right content for a short linear flow; the Stepper page has the decision table for when a flow instead wants a Stepper or a Progress.footerLeadholds leading actions such as Back. With the trailingfooterit forms one action bar: leading actions at the logical start, the primary outcome at the logical end. On narrow widths that single bar can wrap onto more than one line, which is a layout effect, not a second footer. Source order matches focus order, and the logical properties place the bar correctly in right-to-left layouts. A second footer row is never needed.bodyLayout="stack"spaces the body’s direct sections by--ds-dialog-body-gap(1remby default), so a workflow does not invent its own spacing.plainis the default and leaves the body untouched.
Back, dismissal and completion are three different actions
Section titled “Back, dismissal and completion are three different actions”- Back navigates to the previous step. It never dismisses.
- Dismissal leaves the dialog. It stays available at every step: the header
close button is always rendered, and
footerCloseadds one to the footer. Escape also dismisses, and a backdrop press can, but neither replaces a visible, keyboard-focusable control. - Completion is the primary action of the last step.
Name the dismissal for what it actually does in your flow. Close merely
dismisses; Cancel cancels an operation that was never applied; Exit leaves
an ongoing situation; Discard changes says the entered work is lost. These are
examples, not a required vocabulary: the requirement is only that the visible
label communicates the effect.
If your application writes something before the last step, dismissal must not suggest a rollback that does not happen. Defer the side effect, say that it stays, or ask for confirmation. Dialog stays neutral here: it cannot know.
closeLabel names both the header close button and the footerClose button,
so when you use both they share one accessible name.
Focus on a step change
Section titled “Focus on a step change”Dialog moves focus into the panel on open, and initialFocus chooses where.
Between steps, the application moves focus, because only the application knows
a step changed:
<script> import { tick } from "svelte";
let step = $state(1); let heading = $state();
const goTo = async (next) => { step = next; await tick(); heading.focus(); };</script>
<Dialog title="Set up project" bodyLayout="stack" initialFocus=".step-heading"> {#snippet headerMeta()}<span>Step {step} of 2</span>{/snippet} <h3 class="step-heading" tabindex="-1" bind:this={heading}>…</h3></Dialog>- Move focus to the heading of the new step, or to another deliberate starting
point. A static heading takes focus with
tabindex="-1", which lets the new context be read before its controls. - Never leave focus on a control the previous step removed: the browser drops it to the body and the reader loses their place.
- Do not focus the primary action because it looks prominent.
- Going Back needs a destination too, usually the heading of the step you return to.
- A live region is not needed when focus already moves: the new heading is announced by the move itself.
Narrow layouts, zoom and translation
Section titled “Narrow layouts, zoom and translation”The panel is max-inline-size bounded and fluid below it, the body is the only
scrolling region, and the footer wraps. That keeps the workflow usable at 400%
zoom and at a 320 CSS pixel viewport without two-dimensional scrolling, which
WCAG 2.2 Reflow (1.4.10)
requires. Labels are consumer content, so text expansion in translation is
handled by the wrapping footer rather than by fixed widths.
Two distinct levels apply to the controls you put in these regions:
- WCAG 2.2 Target Size (Minimum), 2.5.8, level AA: at least 24 by 24 CSS pixels, with the spacing, inline and essential exceptions. This is a conformance requirement.
- Invisible UI recommends a larger comfortable target, around 44 pixels, for touch. That is a design-system preference, not a WCAG AA requirement.
The same regions in every adapter
Section titled “The same regions in every adapter”Svelte exposes the regions as snippets, Vue as named slots, React as props of the same names.
<ds-dialog> has no Shadow DOM (ADR 0008), so it
marks the regions with a slot attribute on light-DOM children and reads them
once when it renders. Children without the attribute stay the body, exactly as
before, and body-layout mirrors bodyLayout:
<ds-dialog heading="Set up project" trigger="Set up project" body-layout="stack"> <span slot="header-meta">Step 2 of 2</span> <button slot="footer-lead" type="button">Back</button> <button slot="footer" type="button">Create project</button>
<h3 tabindex="-1">Name the project</h3> <label>Project name <input type="text" /></label></ds-dialog>The Reflex wrapper passes the regions as component-valued props, which Reflex compiles to JSX elements:
ui.dialog( "Body", title="Set up project", body_layout="stack", header_meta=rx.text("Step 2 of 2"), footer_lead=ui.button("Back", variant="ghost"), footer=ui.button("Create project", variant="primary"),)What Dialog guarantees, and what stays yours
Section titled “What Dialog guarantees, and what stays yours”Dialog guarantees the modal semantics, the accessible name, focus containment while open, Escape, background inertness, focus return to the trigger on close, the fixed header and footer with body-only scrolling, and the placement of the regions above. The application owns the step state, the step content, the labels, the focus destination on a step change, and any side effect its steps apply.
Import
Section titled “Import”<script> import Dialog from "@invisible-ui/svelte/Dialog.svelte";</script><script setup> import { Dialog } from "@invisible-ui/vue";</script>import { Dialog } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-dialog></ds-dialog>| Prop | Type | Default | Description |
|---|---|---|---|
triggerVariant | "default" | "primary" | "secondary" | "ghost" | "danger" | "default" | Visual variant for the trigger Button. |
open | boolean | false | Initial open state. |
title * | string | — | Accessible title naming the dialog. |
hideTitle | boolean | false | Visually hide the title while keeping it as the dialog's accessible name (announced by screen readers via aria-labelledby). The title text is always required; this only controls whether it is shown. |
description | string | undefined | undefined | Optional description, wired via aria-describedby. |
closeLabel | string | undefined | undefined | Accessible label for the close button. |
closeButton | boolean | true | Show the close button at the trailing end of the header. |
footerClose | boolean | false | Show an optional close/cancel button on the footer's leading (left) edge. The trailing (right) edge holds the action buttons from the footer snippet. |
bodyLayout | "plain" | "stack" | "plain" | Body layout. plain (the default) leaves the body untouched. stack spaces the direct children by --ds-dialog-body-gap, which saves a workflow from inventing its own spacing between sections. |
initialFocus | string | undefined | undefined | CSS selector (within the panel) for the element to focus on open. When omitted, focus lands on the panel itself — never on the close button. |
onOpenChange | ((open: boolean) => void) | undefined | undefined | Called when the dialog opens/closes. |
trigger | Snippet | undefined | undefined | The trigger button's content. Defaults to the i18n catalog's label. |
icon | Snippet | undefined | undefined | Leading feedback icon in the header. |
headerMeta | Snippet | undefined | undefined | Context above the title, e.g. "Step 1 of 2". |
headerLead | Snippet | undefined | undefined | Leading ghost button in the header, e.g. back. |
headerActions | Snippet | undefined | undefined | Actions before the close button. |
footerLead | Snippet | undefined | undefined | Leading footer actions. |
footer | Snippet | undefined | undefined | Trailing footer action buttons. |
| Prop | Type | Default | Description |
|---|---|---|---|
triggerVariant | ButtonVariant | "default" | Visual variant for the trigger Button. |
trigger | string | undefined | The trigger button's label. The trigger slot replaces it with markup. |
open | boolean | false | Initial / controlled open state; bindable with v-model:open. |
title * | string | — | Accessible title naming the dialog (required). |
hideTitle | boolean | false | Visually hide the title while keeping it as the dialog's accessible name. The title text is always required; this only controls whether it is shown. |
description | string | undefined | Optional description, wired via aria-describedby. |
closeLabel | string | undefined | Accessible label for the close button. Defaults to the catalog's "Close". |
closeButton | boolean | true | Show the close button at the trailing end of the header. Default true. |
footerClose | boolean | false | Show a close/cancel button on the footer's leading edge. |
bodyLayout | DialogBodyLayout | "plain" | Body layout. plain (the default) leaves the body untouched. stack spaces the direct children by --ds-dialog-body-gap, which saves a workflow from inventing its own spacing between sections. |
initialFocus | string | undefined | CSS selector (within the panel) for the element to focus on open. When omitted, focus lands on the panel itself, never on the close button. |
closeOnOutsideClick | boolean | true | Whether pressing the backdrop closes. Default true. |
onOpenChange | (open: boolean) => void | undefined |
| Event | Payload |
|---|---|
update:open | open: boolean |
Slots: default, footer, footerLead, headerActions, headerLead, headerMeta, icon, trigger.
| Prop | Type | Default | Description |
|---|---|---|---|
triggerVariant | ButtonVariant | "default" | Visual variant for the trigger Button. |
trigger | ReactNode | — | The trigger button's content. |
open | boolean | false | Initial / controlled open state. |
title * | string | — | Accessible title naming the dialog (required). |
hideTitle | boolean | false | Visually hide the title while keeping it as the dialog's accessible name. The title text is always required; this only controls whether it is shown. |
description | string | — | Optional description, wired via aria-describedby. |
closeLabel | string | — | Accessible label for the close button. Defaults to the catalog's "Close". |
closeButton | boolean | true | Show the close button at the trailing end of the header. Default true. |
icon | ReactNode | — | Leading feedback icon, centered against the title block. |
headerMeta | ReactNode | — | Content above the title, e.g. "Step 1 of 2". Carries no progress semantics. |
headerLead | ReactNode | — | Leading ghost icon button (e.g. a back affordance). |
headerActions | ReactNode | — | Actions before the close button, on the title row. |
footerLead | ReactNode | — | Leading footer actions, e.g. Back. |
footer | ReactNode | — | Trailing action buttons in the footer. |
footerClose | boolean | false | Show a close/cancel button on the footer's leading edge. |
bodyLayout | DialogBodyLayout | "plain" | Body layout. plain (the default) leaves the body untouched. stack spaces the direct children by --ds-dialog-body-gap, which saves a workflow from inventing its own spacing between sections. |
initialFocus | string | — | CSS selector (within the panel) for the element to focus on open. When omitted, focus lands on the panel itself — never on the close button. |
closeOnOutsideClick | boolean | true | Whether pressing the backdrop closes. Default true. |
onOpenChange | (open: boolean) => void | — | |
children | ReactNode | — | The dialog body. |
| Attribute | Reactive | Description |
|---|---|---|
heading * | yes | the global title attribute is a browser tooltip and cannot be used |
description | yes | |
trigger | yes | opener text |
trigger-variant | yes | |
open | yes | |
close-label | yes | |
close-button | yes | "false" drops the close button |
initial-focus | — | CSS selector |
no-outside-close | — | |
body-layout | yes | plain by default, or stack to space the body's direct sections by --ds-dialog-body-gap |
Reactive attributes re-render the element when they change after the first render.
Properties: open (boolean).
Methods: notify(options), dismissNotice(id), clearNotices() (the status area, ADR 0016).
Emits: bubbling open-change CustomEvent with detail.open.
Snippets: trigger (the trigger button’s content), children (the body),
icon (leading feedback icon), headerMeta (context above the title),
headerLead (leading ghost button), footerLead (leading footer actions) and
footer (trailing action buttons). In React the regions are props of the same
names; in Vue they are named slots.
Accessibility
Section titled “Accessibility”- Trigger carries
aria-haspopup="dialog"/aria-expandedand, while open,aria-controls. The panel isrole="dialog"witharia-modal="true", named by its title (aria-labelledby) and optionally described (aria-describedby). - Modal semantics: focus moves into the panel on open, is trapped (Tab
wraps), body scroll is locked; Escape, the close button, or a backdrop
press close it and return focus to the trigger. In the Svelte adapter the
backdrop press always dismisses; the Vue adapter can turn it off with
closeOnOutsideClick— an adapter gap that is on the parity list. - No portal: the native
<dialog>element’s top layer escapes ancestoroverflowand stacking contexts on its own.
Example
Section titled “Example”<Dialog title="Edit profile" description="Make changes to your profile here."> {#snippet trigger()}<span>Edit profile</span>{/snippet} <form>…</form></Dialog>Themeable via --ds-dialog-*. The backdrop paints --ds-components-dialog-overlay-default,
defined per theme in tokens.css: rgb(27 27 27 / 0.5) in light and
rgb(0 0 0 / 0.6) in dark. How far it sets the dialog apart from the page is
a theme choice, not an accessibility requirement. The shared
modal adapter — native <dialog> + showModal() and scroll lock — is reused
across the whole dialog family.