Confirm Dialog
role="dialog").urgent (role="alertdialog").A modal to verify or accept before proceeding — the accessible equivalent of
window.confirm(), one of the platform’s simple dialogs. Cancel stops the
process, confirm proceeds. It reuses the headless dialog and the shared modal
adapter (native <dialog> + showModal(): top layer, inert background,
scroll lock). The trigger is the children snippet;
onConfirm runs when the confirm button is pressed. Focus lands on the safe
choice.
Set urgent when the choice must interrupt: the panel switches to
role="alertdialog" (screen readers announce it immediately) and nothing else
changes — urgency is a modifier, not a different component (the demo above
shows both).
It also works stacked on another dialog — the confirm-on-close case: a Confirm Dialog guarding an edit dialog with unsaved changes. The top layer stacks it above, Escape closes only the confirm, and focus returns into the outer dialog (see the family overview).
Wording
Section titled “Wording”Buttons name outcomes, not gestures. The classic trap: “Do you want to cancel the order?” with Cancel / OK buttons — “Cancel” reads both as “cancel the order” and “close this dialog”, and a screen-reader user hears the bare label with no layout around it to disambiguate. Name what each choice does instead: Cancel order / Keep order (or, in the example below, Delete file / Keep file). Both labels are overridable; the defaults are the conventional “Confirm”/“Cancel”, and the examples here always name the outcome.
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).
Import
Section titled “Import”<script> import ConfirmDialog from "@invisible-ui/svelte/ConfirmDialog.svelte";</script><script setup> import { ConfirmDialog } from "@invisible-ui/vue";</script>import { ConfirmDialog } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-confirm-dialog></ds-confirm-dialog>In Elements:
<ds-confirm-dialog heading="Delete file" description="Do you want to delete “report-q3.pdf”? The file will be permanently deleted." confirm-label="Delete file" cancel-label="Keep file" confirm-variant="danger" trigger="Delete file"></ds-confirm-dialog>
<script type="module"> document .querySelector("ds-confirm-dialog") .addEventListener("confirm", () => deleteFile());</script>urgent switches the panel to role="alertdialog"; close-button adds a
close button to the header.
In React, onConfirm runs on the confirm button, and trigger is the
trigger’s content:
<ConfirmDialog title="Delete file" description="Do you want to delete “report-q3.pdf”? The file will be permanently deleted." confirmLabel="Delete file" cancelLabel="Keep file" confirmVariant="danger" trigger="Delete file" onConfirm={() => deleteFile()}/>| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | false | Initial open state. |
title * | string | — | Accessible title naming the confirmation (required). |
description | string | undefined | undefined | Optional supporting message. |
confirmLabel | string | undefined | undefined | Label of the confirming button. Defaults to the i18n catalog's "Confirm". |
cancelLabel | string | undefined | undefined | Label of the cancelling button (also the Escape action). Defaults to "Cancel". |
confirmVariant | ButtonVariant | "primary" | Variant of the confirm button ("danger" for a destructive-ish confirm). |
urgent | boolean | false | Interrupting urgency: switches the panel to role="alertdialog", which screen readers announce immediately. Nothing else changes (ADR 0005). |
triggerVariant | ButtonVariant | "default" | Visual variant for the trigger Button. |
onConfirm | (() => void) | undefined | undefined | Called when the confirm button is pressed (before the dialog closes). |
closeOnOutsideClick | boolean | true | Whether pressing the backdrop cancels and closes. Defaults to true. |
closeButton | boolean | false | Show a close button at the trailing end of the header; it closes like Escape. |
closeLabel | string | undefined | undefined | Accessible label for the close button. Defaults to the i18n catalog's "Close". |
onOpenChange | ((open: boolean) => void) | undefined | undefined | Called whenever the open state changes. |
icon | Snippet | undefined | undefined | Leading feedback icon in the header. |
| 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 confirmation (required). |
description | string | undefined | Optional supporting message. |
confirmLabel | string | undefined | Label of the confirming button. Defaults to the catalog's "Confirm"; prefer naming the outcome ("Delete file"). |
cancelLabel | string | undefined | Label of the cancelling button (also the Escape action). Defaults to the catalog's "Cancel"; prefer naming the outcome ("Keep file"). |
confirmVariant | ButtonVariant | "primary" | Variant of the confirm button ("danger" for a destructive confirm). |
urgent | boolean | false | Interrupting urgency: switches the panel to role="alertdialog", which screen readers announce immediately. Nothing else changes (ADR 0005). |
onConfirm | () => void | undefined | Called when the confirm button is pressed (before the dialog closes). |
closeOnOutsideClick | boolean | true | Whether pressing the backdrop cancels and closes. Defaults to true. |
closeButton | boolean | false | Show a close button at the trailing end of the header; it closes like Escape. |
closeLabel | string | undefined | Accessible label for the close button. Defaults to the catalog's "Close". |
onOpenChange | (open: boolean) => void | undefined |
| Event | Payload |
|---|---|
update:open | open: boolean |
Slots: icon, trigger.
| Prop | Type | Default | Description |
|---|---|---|---|
triggerVariant | ButtonVariant | "default" | Visual variant for the trigger Button. |
trigger | ReactNode | — | The trigger button's content. Defaults to the catalog's "Open". |
open | boolean | false | Initial / controlled open state. |
title * | string | — | Accessible title naming the confirmation (required). |
description | string | — | Optional supporting message. |
confirmLabel | string | — | Label of the confirming button. Defaults to the catalog's "Confirm". |
cancelLabel | string | — | Label of the cancelling button (also the Escape action). Defaults to "Cancel". |
confirmVariant | ButtonVariant | "primary" | Variant of the confirm button ("danger" for a destructive confirm). |
urgent | boolean | false | Interrupting urgency: switches the panel to role="alertdialog", which screen readers announce immediately. Nothing else changes (ADR 0005). |
onConfirm | () => void | — | Called when the confirm button is pressed (before the dialog closes). |
closeOnOutsideClick | boolean | true | Whether pressing the backdrop cancels and closes. Defaults to true. |
closeButton | boolean | false | Show a close button at the trailing end of the header; it closes like Escape. |
closeLabel | string | — | Accessible label for the close button. Defaults to the catalog's "Close". |
icon | ReactNode | — | Leading feedback icon in the header. |
onOpenChange | (open: boolean) => void | — | Called whenever the open state changes. |
| Attribute | Reactive | Description |
|---|---|---|
heading * | yes | |
description | yes | |
confirm-label | yes | "Confirm" by default |
cancel-label | yes | "Cancel" by default |
confirm-variant | yes | primary by default, danger for a destructive confirm |
urgent | yes | |
trigger | yes | opener text |
trigger-variant | yes | |
open | yes | |
close-button | yes | shows a close button in the header |
close-label | yes | |
no-outside-close | — |
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, and confirm when the confirm button is pressed.
Accessibility
Section titled “Accessibility”role="dialog",aria-modal, named by itstitleand described by the optional message. Escape and a backdrop press cancel (setcloseOnOutsideClick={false}to require an explicit choice).- Focus is trapped in the panel and starts on the Cancel button; it returns to the trigger on close.
Example
Section titled “Example”<ConfirmDialog title="Delete file" description="Do you want to delete “report-q3.pdf”? The file will be permanently deleted." confirmLabel="Delete file" cancelLabel="Keep file" confirmVariant="danger" onConfirm={() => remove()}> Delete file</ConfirmDialog>Themeable via --ds-dialog-*.