Skip to main content

Installation

yarn add @twilio-paste/alert-dialog

Usage

import { AlertDialog } from '@twilio-paste/alert-dialog';
import { Button } from '@twilio-paste/button';

const MyAlertDialog = () => {
  const [isOpen, setIsOpen] = React.useState(false);

  return (
    <>
      <Button variant="primary" onClick={() => setIsOpen(true)}>
        Delete Item
      </Button>
      <AlertDialog
        heading="Delete data"
        isOpen={isOpen}
        onConfirm={() => {
          // Handle delete action
          setIsOpen(false);
        }}
        onConfirmLabel="Delete"
        onDismiss={() => setIsOpen(false)}
        onDismissLabel="Cancel"
      >
        Are you sure you want to delete this data? This action cannot be undone.
      </AlertDialog>
    </>
  );
};

Props

AlertDialog

PropTypeDefaultDescription
headingstring-Required. Header text for the Alert Dialog.
isOpenboolean-Required. Determines whether the Alert Dialog is open.
onConfirm() => void-Required. Function to run when the confirm button is clicked.
onConfirmLabelstring-Required. Label for the confirm button.
onDismiss() => void-Required. Function to run when the dismiss button is clicked or dialog is closed.
onDismissLabelstring-Required. Label for the dismiss button.
childrenReact.ReactNode-Required. The message body content.
destructivebooleanfalseDisplay a destructive Alert Dialog with warning styling.
isConfirmDisabledbooleanfalseDisable the confirm button.
elementstring"ALERT_DIALOG"Overrides the default element name for custom styling with the Customization Provider.

Examples

Default Alert Dialog

<AlertDialog
  heading="Submit application"
  isOpen={isOpen}
  onConfirm={handleConfirm}
  onConfirmLabel="Submit"
  onDismiss={handleDismiss}
  onDismissLabel="Cancel"
>
  Are you sure you want to submit this application? No information can be changed after submitting.
</AlertDialog>

Destructive Alert Dialog

<AlertDialog
  heading="Delete data"
  isOpen={isOpen}
  destructive
  onConfirm={handleDelete}
  onConfirmLabel="Delete"
  onDismiss={handleDismiss}
  onDismissLabel="Cancel"
>
  Are you sure you want to delete this data? This action cannot be undone.
</AlertDialog>

Disabled Confirm Button

const [inputValue, setInputValue] = React.useState('');
const isDisabled = inputValue !== 'DELETE';

<AlertDialog
  heading="Delete regulatory bundle"
  isOpen={isOpen}
  destructive
  onConfirm={handleConfirm}
  onConfirmLabel="Delete"
  onDismiss={handleDismiss}
  onDismissLabel="Cancel"
  isConfirmDisabled={isDisabled}
>
  <p>You're about to delete "Toyota TCB Automobile" and all data associated with it.</p>
  <Label htmlFor="delete-input" required>
    Regulatory bundle name
  </Label>
  <Input
    id="delete-input"
    value={inputValue}
    onChange={(e) => setInputValue(e.target.value)}
  />
  <HelpText>To confirm this deletion, please input DELETE.</HelpText>
</AlertDialog>

Accessibility

  • AlertDialog uses role="alertdialog" for screen readers
  • Both aria-labelledby and aria-describedby are automatically set
  • Focus is trapped within the dialog when open
  • Pressing Escape triggers the onDismiss callback
  • Clicking outside the dialog triggers the onDismiss callback
  • The dialog is announced to screen readers when it opens

When to Use

Use Alert Dialog when:

  • You need to interrupt the user’s workflow for critical information
  • You need confirmation before performing a destructive action
  • The user must acknowledge important information before continuing
  • You need a simple yes/no or confirm/cancel response

Use Modal instead when:

  • You need a more complex form or multi-step workflow
  • The content is not urgent or critical
  • You need custom header content or multiple sections
  • The dialog doesn’t require an immediate binary decision

Build docs developers (and LLMs) love