Confirm Dialog

Usage

ConfirmDialog is the page pattern for confirming an action. Declare it once per action, give it copy, and report the action with onConfirm. Do not assemble a confirm from AlertDialog parts in a page.

Copy

title, description, confirmLabel, and cancelLabel are required LocalizedMessage props. Name the affected thing in description ("This removes incident 4521 and its notes. It cannot be undone."), and name the confirm for its action ("Delete", "Remove", "End shift"), never "Confirm" or "OK". The cancel is "Cancel" by default; use a domain-specific label such as "Keep incident" only where the copy is about that domain. A prompt that appears when a dirty form closes uses "Keep editing" for the cancel and "Discard" for the confirm (ADR 0023, decision 10). pendingLabel ("Deleting incident") names the confirm Button and is announced while a confirm is pending.

Variant

ConfirmDialogVariant.Destructive paints a destructive solid confirm for an irreversible action. The default paints an accent solid confirm. Focus starts on the cancel in both.

Async actions

Return a promise from onConfirm and the block does the rest:

The confirm Button shows its loading state. It is loading, not disabled.
The cancel Button is unavailable, and Escape does not close the dialog.
A fulfilled promise closes the dialog; the caller's onOpenChange is called with close-press. If the caller vetoes that close, the dialog stays open and focus returns to the confirm Button.
A rejected promise keeps the dialog open and puts focus back on the confirm Button. The rejection is not rethrown. Report it from the handler and pass error:

A handler that returns nothing closes the dialog at once. Either way a confirm runs at most once per open session: pressing the confirm again while the dialog closes does not run it twice. A rejection, or a close you veto, makes it available again.

Open state

Uncontrolled, the trigger opens the dialog and defaultOpen opens it on mount. Controlled, pass open and onOpenChange, as a list page does with one shared dialog and the row it picked. onOpenChange(false, details) is called for the cancel, a fulfilled confirm, and Escape; details.cancel() keeps it open. A backdrop press never closes it.

More content

children renders between the description and the actions: the records an action affects. A typed confirmation field sits below it.

Typed confirmation

For an action that is hard to undo, ask the person to type what they are deleting. Pass confirmation={ConfirmDialogConfirmation.Typed}, the phrase to type, and the sentence around it:

Single delete: phrase is the record's name, so the person types the name of the record they are about to delete.
Bulk delete: phrase is a fixed word the product picks once (such as DELETE), whatever the count.
Copy: the label reads instruction, then the phrase, then instructionEnd, as one sentence ("To continue, type User Permissions in the field below."). The block places the phrase so it can set it apart, so do not repeat it in either part. Name the confirm for the action ("Delete", not "Confirm") and the cancel "Cancel" or what it keeps. All copy is LocalizedMessage; the phrase is data.
The match: leading and trailing whitespace is ignored, both sides are normalized to Unicode NFC, and the comparison is case-sensitive. Whitespace inside the text counts. An empty phrase never matches.
Keyboard: the field holds focus when the dialog opens. Enter confirms once the text matches and does nothing before. Tab reaches the cancel, and the confirm once it is available.
Reopening: the field is empty and the confirm is unavailable each time the dialog opens. The text stays while the dialog fades out.
Pending: a confirm that returns a promise holds the text read-only and shows the loading state, as in Async actions.
Extra content: children renders above the field, so list the records an action affects there.

confirmDisabled still works and combines with the match: the confirm is available only when both allow it.

Styles

Load the stylesheets of what it composes: alert-dialog/styles.css, dialog/styles.css, button/styles.css, text/styles.css, box/styles.css, and visually-hidden/styles.css, with blocks/confirm-dialog/styles.css. A typed dialog also needs input/styles.css and label/styles.css.

Composed Empty State / Accessibility

Confirm Dialog / API and Development

On this page

Confirm Dialog

Usage

Copy

Variant

ConfirmDialogVariant.Destructive paints a destructive solid confirm for an irreversible action. The default paints an accent solid confirm. Focus starts on the cancel in both.

Async actions

Return a promise from onConfirm and the block does the rest:

The confirm Button shows its loading state. It is loading, not disabled.
The cancel Button is unavailable, and Escape does not close the dialog.
A fulfilled promise closes the dialog; the caller's onOpenChange is called with close-press. If the caller vetoes that close, the dialog stays open and focus returns to the confirm Button.
A rejected promise keeps the dialog open and puts focus back on the confirm Button. The rejection is not rethrown. Report it from the handler and pass error:

Open state

More content

children renders between the description and the actions: the records an action affects. A typed confirmation field sits below it.

Typed confirmation

For an action that is hard to undo, ask the person to type what they are deleting. Pass confirmation={ConfirmDialogConfirmation.Typed}, the phrase to type, and the sentence around it:

Single delete: phrase is the record's name, so the person types the name of the record they are about to delete.
Bulk delete: phrase is a fixed word the product picks once (such as DELETE), whatever the count.
Copy: the label reads instruction, then the phrase, then instructionEnd, as one sentence ("To continue, type User Permissions in the field below."). The block places the phrase so it can set it apart, so do not repeat it in either part. Name the confirm for the action ("Delete", not "Confirm") and the cancel "Cancel" or what it keeps. All copy is LocalizedMessage; the phrase is data.
The match: leading and trailing whitespace is ignored, both sides are normalized to Unicode NFC, and the comparison is case-sensitive. Whitespace inside the text counts. An empty phrase never matches.
Keyboard: the field holds focus when the dialog opens. Enter confirms once the text matches and does nothing before. Tab reaches the cancel, and the confirm once it is available.
Reopening: the field is empty and the confirm is unavailable each time the dialog opens. The text stays while the dialog fades out.
Pending: a confirm that returns a promise holds the text read-only and shows the loading state, as in Async actions.
Extra content: children renders above the field, so list the records an action affects there.

confirmDisabled still works and combines with the match: the confirm is available only when both allow it.

Styles

Composed Empty State / Accessibility

Confirm Dialog / API and Development

On this page