Put the opening control in slot="trigger" and the two decisions in slot="cancel" and slot="confirm". label and description become the visible title and consequence text. Outside clicks never close an Alert Dialog; only Cancel, Confirm or Escape do.
It always traps focus and blocks background interaction: the whole document by default, or only one container with modality="container". Use Dialog for general workflows. Alert Dialog shares Dialog’s state, native surface, focus, triggers, handles, nesting and presence; only its decision policy and public part names differ.
Confirming
Cancel closes on its own. Confirm only supplies the button: clicking it does nothing until your handler performs the work and then closes the dialog with setOpen(false, 'close-action', event). State mode is fixed at first render. Use setOpen() for programmatic changes in uncontrolled mode. In controlled mode, accept tp-open-change by assigning dialog.open = event.detail.value.
Asynchronous confirm
Default density
Compact density
Restart from the initial state
Show the copyable source
For slow work, keep the dialog open, show progress on Confirm and lock Cancel until the request settles. If it fails, put the error in the dialog content instead of closing.
Content
Media and body
Default density
Compact density
Restart from the initial state
Show the copyable source
Close editor
You have unsaved changes to Onboarding checklist. They will be lost if you leave now.
Keep editingDiscard changes
Close editor
You have unsaved changes to Onboarding checklist. They will be lost if you leave now.
Keep editingDiscard changes
<tp-alert-dialog id="alert-dialog-media" label="Leave without saving?">
<tp-button slot="trigger" variant="outline">Close editor</tp-button>
<svg slot="media" aria-hidden="true" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3"/><path d="M12 9v4M12 17h.01"/></svg>
<p slot="description">You have unsaved changes to <strong>Onboarding checklist</strong>. They will be lost if you leave now.</p>
<tp-button slot="cancel" variant="outline">Keep editing</tp-button>
<tp-button slot="confirm" id="alert-dialog-media-confirm">Discard changes</tp-button>
</tp-alert-dialog>
<script type="module">
const dialog = document.querySelector('#alert-dialog-media');
document.querySelector('#alert-dialog-media-confirm').addEventListener('click', (event) => {
dialog.setOpen(false, 'close-action', event);
});
</script>
The title, description and media slots take rich content when the attributes are not enough. Label both actions with their outcome, such as “Keep editing” and “Discard changes”, rather than “OK”. Alert Dialog has no generic corner Close: its named Cancel and Confirm actions communicate the decision.
Alert Dialog renders in a native dialog in the browser top layer, which escapes clipping and transformed ancestors while slotted content keeps inherited tokens. The inherited Dialog portal properties move it to another destination; with container modality it renders in place inside the container.
Focus
Initial focus on Confirm
Default density
Compact density
Restart from the initial state
Show the copyable source
PublishNot yetPublish
PublishNot yetPublish
<tp-alert-dialog
id="alert-dialog-focus"
initial-focus="confirm"
label="Publish changes?"
description="Your edits to Pricing will be visible to everyone with the link."
>
<tp-button slot="trigger">Publish</tp-button>
<tp-button slot="cancel" variant="outline">Not yet</tp-button>
<tp-button slot="confirm" id="alert-dialog-focus-confirm">Publish</tp-button>
</tp-alert-dialog>
<script type="module">
const dialog = document.querySelector('#alert-dialog-focus');
document.querySelector('#alert-dialog-focus-confirm').addEventListener('click', (event) => {
dialog.setOpen(false, 'close-action', event);
});
</script>
Opening focuses Cancel by default, so a stray Enter never confirms a destructive action. initial-focus="confirm" suits safe, expected confirmations. Focus stays inside the dialog while it is open and returns to the trigger when it closes.
API Reference
Every element also accepts motion-policy.
Events
EventTypeDescriptiontp-open-changeTpSurfaceOpenChangeEventCancelable proposal to open or close, before the dialog changes; detail.value is the proposed state and detail.reason what asked (trigger-press, close-action, escape-key, outside-press, imperative-action and others). On a close, detail.preventUnmountOnClose() keeps the content mounted.tp-open-change-completeCustomEvent<{ open: boolean; }>After the dialog finishes opening or closing; detail.open.
Slots
SlotDescriptionmediaAn Icon or image above the title that marks the kind of decision.cancelThe action that declines; it closes the dialog when pressed.confirmThe action that carries out the decision; its handler does the work, then closes the dialog.actionsFurther footer actions beside Cancel and Confirm.defaultThe body of the task.triggerThe control that opens the dialog, usually a Button.titleThe title, in place of label.descriptionThe description, in place of description.footerFooter content with no close behavior, such as a secondary action.closeAn action that closes the dialog when pressed, after its own handlers.
Related
Components, widgets and patterns that use this one.