Skip to content

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.

  • 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).
<script>
import AlertDialog from "@invisible-ui/svelte/AlertDialog.svelte";
</script>

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()}
/>
PropTypeDefaultDescription
openbooleanfalseInitial open state.
title *string—Accessible title naming the alert.
description *string—Description of the consequence.
dismissLabelstring | undefinedundefinedLabel of the single acknowledging button. Defaults to the i18n catalog's "OK"; prefer naming the outcome in context ("Done", "Close", "I understood").
triggerVariantButtonVariant"default"Visual variant for the trigger Button.
onDismiss(() => void) | undefinedundefinedCalled when the alert is acknowledged (button, Escape or backdrop).
closeOnOutsideClickbooleantrueWhether 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).
closeButtonbooleanfalseShow a close button at the trailing end of the header; it closes like Escape.
closeLabelstring | undefinedundefinedAccessible label for the close button. Defaults to the i18n catalog's "Close".
onOpenChange((open: boolean) => void) | undefinedundefinedCalled when the alert opens/closes.
iconSnippet | undefinedundefinedLeading feedback icon in the header.

The children snippet is the trigger’s content.

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.

  • Panel is role="alertdialog" with aria-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 (onDismiss runs in every case) — there is no destructive path to protect.
<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).