molecule

AlertDialog

Confirmation dialog with confirm/cancel buttons for destructive or important actions. Consumer handles async logic.

Overview

The AlertDialog component is a specialized modal for confirmation prompts before destructive or important actions. It provides confirm and cancel buttons — the consumer handles any async operations and error display (e.g., via Toast). Use it for delete confirmations, destructive action warnings, and important decision prompts.

import { AlertDialog, Button } from '@enara-health/ui-react';

const [isOpen, setIsOpen] = useState(false);

<Button onClick={() => setIsOpen(true)}>Delete Item</Button>

<AlertDialog
  open={isOpen}
  onOpenChange={setIsOpen}
  title="Delete item?"
  description="This action cannot be undone. The item will be permanently removed."
  onConfirm={handleDelete}
  confirmButtonText="Delete"
  cancelButtonText="Cancel"
/>

Props

Prop	Type	Default	Description
`open`	`boolean`	-	Required. Whether the dialog is visible
`onOpenChange`	`(open: boolean) => void`	-	Required. Callback when open state changes
`title`	`string`	-	Required. Dialog title
`description`	`string`	-	Required. Description text explaining the action
`onConfirm`	`() => void`	-	Required. Handler called when confirm button is clicked
`confirmButtonText`	`string`	-	Required. Label for the confirm button
`onCancel`	`() => void`	-	Optional handler called when cancel button is clicked
`cancelButtonText`	`string`	-	Label for the cancel button (button hidden if omitted)
`trigger`	`ReactNode`	-	Optional trigger element rendered alongside the dialog
`persistent`	`boolean`	`false`	Prevents closing via Escape or backdrop click

Variants

Basic Confirmation

Simple confirm/cancel prompt for important actions.

<AlertDialog
  open={isOpen}
  onOpenChange={setIsOpen}
  title="Delete item?"
  description="This action cannot be undone."
  onConfirm={handleDelete}
  confirmButtonText="Delete"
  cancelButtonText="Cancel"
/>

With Async Confirmation (Consumer-Handled)

AlertDialog only confirms intent — the consumer handles async operations, loading states, and error display (e.g., via Toast).

const handleConfirm = async () => {
  try {
    await deleteItem(itemId);
  } catch (error) {
    showToast({ type: 'error', message: 'Failed to delete item.' });
  }
};

<AlertDialog
  open={isOpen}
  onOpenChange={setIsOpen}
  title="Delete item?"
  description="This action cannot be undone."
  onConfirm={handleConfirm}
  confirmButtonText="Delete"
  cancelButtonText="Cancel"
/>

Examples

Delete Confirmation

Standard pattern for confirming destructive delete actions.

<AlertDialog
  open={showDeleteDialog}
  onOpenChange={setShowDeleteDialog}
  title="Delete patient record?"
  description="This will permanently remove the patient record and all associated data. This action cannot be undone."
  onConfirm={handleDeletePatient}
  confirmButtonText="Delete Record"
  cancelButtonText="Cancel"
/>

Save Before Leaving

Prompt users to save changes before navigating away.

<AlertDialog
  open={hasUnsavedChanges && isNavigating}
  onOpenChange={setIsNavigating}
  title="Unsaved changes"
  description="You have unsaved changes. Do you want to save before leaving?"
  onConfirm={handleSaveAndLeave}
  onCancel={handleDiscardAndLeave}
  confirmButtonText="Save & Leave"
  cancelButtonText="Discard"
  persistent
/>

Confirm-Only (No Cancel)

Omit cancelButtonText to show only the confirm button.

<AlertDialog
  open={isOpen}
  onOpenChange={setIsOpen}
  title="Action completed"
  description="The export has been queued and will be ready shortly."
  onConfirm={() => setIsOpen(false)}
  confirmButtonText="OK"
/>

Accessibility

Best Practices

Use AlertDialog for simple confirm/cancel flows — use Dialog for complex forms
Write clear, specific descriptions that explain the consequences of the action
Use descriptive button labels (e.g., "Delete Record" instead of "OK")
Handle async operations and errors in the consumer (e.g., show Toast on failure)