Skip to content

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.

  • 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 (urgent to interrupt).
  • Prompt Dialog — asks for a single value (optional, required, or gated by confirmValue; urgent to interrupt).
  • Search Dialog — a quick search: search by keyword and pick from a list.
  • Sheet Dialog — a task in an edge-anchored panel (side variant, optional drag-to-dismiss).

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>

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):

  1. 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).
  2. Unrelated, and it can wait: the Notification Region holds it and shows it after the dialog closes.
  3. 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.

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.

  • headerMeta holds the step context above the title, for example Step 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.
  • footerLead holds leading actions such as Back. With the trailing footer it 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 (1rem by default), so a workflow does not invent its own spacing. plain is 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 footerClose adds 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.

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.

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.

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.

<script>
import Dialog from "@invisible-ui/svelte/Dialog.svelte";
</script>
PropTypeDefaultDescription
triggerVariant"default" | "primary" | "secondary" | "ghost" | "danger""default"Visual variant for the trigger Button.
openbooleanfalseInitial open state.
title *string—Accessible title naming the dialog.
hideTitlebooleanfalseVisually 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.
descriptionstring | undefinedundefinedOptional description, wired via aria-describedby.
closeLabelstring | undefinedundefinedAccessible label for the close button.
closeButtonbooleantrueShow the close button at the trailing end of the header.
footerClosebooleanfalseShow 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.
initialFocusstring | undefinedundefinedCSS 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) | undefinedundefinedCalled when the dialog opens/closes.
triggerSnippet | undefinedundefinedThe trigger button's content. Defaults to the i18n catalog's label.
iconSnippet | undefinedundefinedLeading feedback icon in the header.
headerMetaSnippet | undefinedundefinedContext above the title, e.g. "Step 1 of 2".
headerLeadSnippet | undefinedundefinedLeading ghost button in the header, e.g. back.
headerActionsSnippet | undefinedundefinedActions before the close button.
footerLeadSnippet | undefinedundefinedLeading footer actions.
footerSnippet | undefinedundefinedTrailing footer action buttons.

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.

  • Trigger carries aria-haspopup="dialog" / aria-expanded and, while open, aria-controls. The panel is role="dialog" with aria-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 ancestor overflow and stacking contexts on its own.
<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.