Alert Dialog
A modal acknowledgement — the accessible equivalent of window.alert(), the
first of the platform’s simple dialogs. It interrupts to communicate an
important message (role="alertdialog", announced immediately by screen
readers), but there is nothing to cancel: one button takes note and closes.
Escape and a backdrop press are equivalent to the button; set
closeOnOutsideClick={false} to require an explicit press (e.g. a notice the
user must actively acknowledge).
If the dialog offers a choice — something that can stop a process — it is not
an alert: use Confirm Dialog
(with urgent if it must interrupt), or
Prompt Dialog if it asks for
a value.
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 AlertDialog from "@invisible-ui/svelte/AlertDialog.svelte";</script><script setup> import { AlertDialog } from "@invisible-ui/vue";</script>import { AlertDialog } from "@invisible-ui/react";<script type="module"> import "@invisible-ui/elements/define";</script>
<ds-alert-dialog></ds-alert-dialog>In Elements:
<ds-alert-dialog heading="File deleted" description="“report-q3.pdf” was permanently deleted." dismiss-label="Done" trigger="Show outcome"></ds-alert-dialog>
<script type="module"> document .querySelector("ds-alert-dialog") .addEventListener("dismiss", () => refresh());</script>The dismiss event fires for the button, Escape and a backdrop press alike.
close-button adds a close button to the header.
In React, trigger is the trigger’s content and a ref holds the status area:
<AlertDialog title="File deleted" description="“report-q3.pdf” was permanently deleted." dismissLabel="Done" trigger="Show outcome" onDismiss={() => refresh()}/>| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | false | Initial open state. |
title * | string | — | Accessible title naming the alert. |
description * | string | — | Description of the consequence. |
dismissLabel | string | undefined | undefined | Label of the single acknowledging button. Defaults to the i18n catalog's "OK"; prefer naming the outcome in context ("Done", "Close", "I understood"). |
triggerVariant | ButtonVariant | "default" | Visual variant for the trigger Button. |
onDismiss | (() => void) | undefined | undefined | Called when the alert is acknowledged (button, Escape or backdrop). |
closeOnOutsideClick | boolean | true | Whether pressing the backdrop (outside the panel) cancels and closes. Defaults to true; set false to force an explicit Cancel/confirm choice (e.g. for irreversible actions). |
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 when the alert opens/closes. |
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 alert (required). |
description * | string | — | The message to acknowledge (required). |
dismissLabel | string | undefined | Label of the single acknowledging button. Defaults to the catalog's "OK"; prefer naming the outcome in context ("Done", "Close", "I understood"). |
onDismiss | () => void | undefined | Called when the alert is acknowledged (button, Escape or backdrop). |
closeOnOutsideClick | boolean | true | Whether pressing the backdrop acknowledges and closes. Defaults to true; set false to require an explicit button press (e.g. "I understood"). |
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 alert (required). |
description * | string | — | The message to acknowledge (required). |
dismissLabel | string | — | Label of the single acknowledging button. Defaults to the catalog's "OK"; prefer naming the outcome in context ("Done", "Close", "I understood"). |
onDismiss | () => void | — | Called when the alert is acknowledged (button, Escape or backdrop). |
closeOnOutsideClick | boolean | true | Whether pressing the backdrop acknowledges and closes. Defaults to true; set false to require an explicit button press (e.g. "I understood"). |
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 | |
dismiss-label | yes | the button, "OK" by default |
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 dismiss when the alert is acknowledged.
The children snippet is the trigger’s content.
Wording
Section titled “Wording”The default label is the conventional “OK”, but prefer naming the outcome in context: Done after an operation, Close for a plain notice, I understood when the user is taking on an obligation. Same principle as the family’s button copy guideline: buttons name outcomes, not gestures.
Accessibility
Section titled “Accessibility”- Panel is
role="alertdialog"witharia-modal="true", named by the title and described by the message (both required). Screen readers announce the content immediately — that is what the role is for. - Focus starts on the only button; focus is trapped and body scroll locked; focus returns to the trigger on close.
- Escape and a backdrop press acknowledge exactly like the button
(
onDismissruns in every case) — there is no destructive path to protect.
Example
Section titled “Example”<AlertDialog title="File deleted" description="“report-q3.pdf” was permanently deleted." dismissLabel="Done" onDismiss={() => refresh()}> Show outcome</AlertDialog>Themeable via --ds-dialog-* (shared with Dialog).