Alert Dialog
Confirm, inform, or report a result from an imperative call.
Anatomy#
<AlertDialog> mounts a host with no DOM of its own. Each call opens a dialog whose panel is
content, with a header for the icon and copy, and a footer for the cancel and action
buttons.
Usage#
Use Alert Dialog for a short confirm, info, warning, error, or success prompt opened from an event handler. Use Dialog when the task has its own trigger, body, and footer.
Mount <AlertDialog> once. It renders no children and holds no open state. Props on the host are
live defaults for every dialog, and options passed to a method override them. Only undefined
falls back to the host: false, 0, and null on a call are kept, so closable: false or
align: null overrides a host default. A call before the host is mounted throws. On the server, a
call returns a handle whose result() is already 'api'.
Give each host a unique id when more than one is mounted. A call without hostId goes to the host
without an id and throws if only hosts with an id are mounted. Pass hostId to target
<AlertDialog id="billing" />. Unmounting a host settles its open dialogs as 'api' and removes
them immediately.
Shared model#
Alert Dialog and Toast use the same options, actions, handle, and close reasons. Every instance is created with a static method that takes an options object.
action.onClick and cancel.onClick run before the instance closes. A returned promise shows
loading on that button and disables the other one. A dialog also blocks Escape, the overlay, and
the corner close button while that promise is pending. A toast pauses its timer. Calling
event.preventDefault(), rejecting, or throwing leaves the instance open. A throw or rejection is
reported with console.error. Otherwise the instance closes with 'action' or 'cancel'.
handle.close() and close(id) close with 'api'. Escape, the overlay, the corner close button,
and a toast swipe close with 'dismiss' and do not run the cancel handler. A toast timer closes
with 'timeout'. result() resolves once with that reason, and calling it again returns the same
promise. The handle itself is not a promise.
update merges the next options into an open instance; options set to undefined are ignored. An
update after close does not reopen it. Reusing an open id with the same method and render updates
that instance in place. With a different method or render, the open dialog closes with 'api' and a
new one opens. update replaces action and cancel as a whole, so include onClick again when
the label changes.
Custom content has two entry points. AlertDialog.custom(render, options?) supplies a render for
that call, either a static JSX.Element or a Component<DialogRenderProps>. The host’s
<AlertDialog dialogRender={render} /> supplies a reusable render for every other call on that
host. It must be a Component<DialogRenderProps>, because the host creates a fresh instance for
each dialog. A .custom() render wins, then the host dialogRender, then the built-in layout. The
render receives the id, the resolved options, pending(), action(), cancel(), close(),
update(), titleId, and descriptionId. It replaces the inner content. The dialog keeps its
overlay, focus trap, role="alertdialog", and panel width.
Methods#
show, info, warning, error, and success show the action button only. confirm shows
cancel as well. Set cancel: true to use the locale label, cancel: { label } to change it, or
cancel: false to hide it on a confirm. info, success, warning, and error set type, which
picks the leading icon and its color; icon replaces the icon. The action button keeps its neutral
tone, so pass action: { tone: 'danger' } for a destructive action.
close() closes every open dialog. close(id) closes one. close({ hostId }) closes every dialog on
that host, and close({ hostId, id }) closes one dialog there. All settle with 'api' before the exit
transition finishes. Unmounting a host also closes its dialogs with 'api' and calls onClose.
AlertDialog.update(id, options) updates the open dialog with that id on any host, like
handle.update.
Defaults#
Action and cancel labels use the dialog message group (ok, cancel) when label is omitted.
Set translations on the host or a call to change these labels and the corner button’s close
label. closable shows the corner close button and defaults to false. title names the dialog.
Only custom calls may omit it; they name the dialog with ariaLabel, or by putting titleId on
the custom heading so aria-labelledby points at it.
Layout#
variant="subtle" gives the footer a top border and muted background. align="center" stacks the
icon, title, and description and stretches the actions into an equal row. Both are props of the host
and options of a call.
Dismissal#
A pointer press on the overlay dismisses the dialog when closeOnOverlayClick is true (default
false). Escape dismisses it unless closeOnEscape is false (default true). The corner close
button appears when closable is true. Escape closes only the topmost dialog. All three settle
with 'dismiss'.
transition on the host sets the default for every dialog on it, and the same option in a call
overrides it. transition: false unmounts a closed dialog without its exit animation.
Custom content#
custom is for a layout the built-in title, description, and actions cannot express. Call
props.action() and props.cancel() so loading, dismissal, and result() stay shared with the
default buttons.
Examples#
Revoke an API key#
confirm returns a handle. Wait on result() and continue when the reason is 'action'.
Show info, warning, error, and success#
Each method sets the type, which picks the icon and its color. Cancel stays hidden until you set cancel.
Update a publish confirm when checks finish#
update changes the open dialog when background verification passes. Include onClick again,
because the next action replaces the previous one.
Authorize a hardware security key#
align="center" stacks the icon and copy. variant="subtle" gives the action row a muted
background and a top border.
Type the name to confirm#
.custom() replaces the inner content and still uses props.action() for the pending state and
the close reason.
API Reference#
Props#
Props for the AlertDialog host component.