Skip to contentSkip to navigationSkip to topbar
Paste assistant Assistant
Figma
Star

Alert Dialog

Version 9.2.0GithubStorybookPeer review pending

An Alert Dialog is a page overlay that displays critical information, blocks interaction with the page, and only closes after an action is performed.

Component preview theme
const AlertDialogTrigger = () => {
const [isOpen, setIsOpen] = React.useState(false);
const handleOpen = () => setIsOpen(true);
const handleClose = () => setIsOpen(false);
return (
<div>
<Button variant="primary" onClick={handleOpen}>
Open alert dialog
</Button>
<AlertDialog
heading="Submit application"
isOpen={isOpen}
onConfirm={handleClose}
onConfirmLabel="Submit"
onDismiss={handleClose}
onDismissLabel="Cancel"
>
Are you sure you want to submit this application? No information can be changed after submitting.
</AlertDialog>
</div>
);
};
render(
<AlertDialogTrigger />
)

Guidelines

Guidelines page anchor

About Alert Dialog

About Alert Dialog page anchor

The Alert Dialog should be used to interrupt a user flow until a specific action is taken. It is used to convey important messages that can't be ignored like Alerts and confirmation messages for deletions. Potential use cases for an Alert Dialog are:

  • Confirming a permanent change, like deleting data
  • Relaying an important system message like a maintenance downtime window

Though visually similar to a Modal, an Alert Dialog requires the user to acknowledge the information in the dialog before they can interact with outside content.

Avoid using Alert Dialogs for error messages. Since the Alert Dialog blocks interaction with the underlying page, the user loses access to the information contained in the message when they go to fix the error. Instead, refer to the error message pattern for additional guidance on components.

When the Alert Dialog opens, focus moves to an element contained in it (by default, the first element that can be focused), and the focus should stay in and cycle through the Alert Dialog's content. Focus shouldn't return to the underlying page until the user closes the Alert Dialog. This can happen in any of the following ways:

  • Presses a "Cancel" button in the Alert Dialog footer
  • Presses a "Submit" or "Confirm" button in the Alert Dialog footer
  • All elements required to interact with the Alert Dialog, including closing or acknowledging it, are contained in the Alert Dialog since they trap focus, and users can't interact with the underlying page.
  • Tabbing through an Alert Dialog will cycle through its content in the same way it does on a page.
  • The element that serves as the Alert Dialog container has a role of alertdialog.
  • The Alert Dialog is labelled by the heading prop.
Component preview theme
const AlertDialogTrigger = () => {
const [isOpen, setIsOpen] = React.useState(false);
const handleOpen = () => setIsOpen(true);
const handleClose = () => setIsOpen(false);
return (
<div>
<Button variant="primary" onClick={handleOpen}>
Open alert dialog
</Button>
<AlertDialog
heading="Submit application"
isOpen={isOpen}
onConfirm={handleClose}
onConfirmLabel="Submit"
onDismiss={handleClose}
onDismissLabel="Cancel"
>
Are you sure you want to submit this application? No information can be changed after submitting.
</AlertDialog>
</div>
);
};
render(
<AlertDialogTrigger />
)

Destructive Alert Dialog

Destructive Alert Dialog page anchor
Component preview theme
const AlertDialogTrigger = () => {
const [isOpen, setIsOpen] = React.useState(false);
const handleOpen = () => setIsOpen(true);
const handleClose = () => setIsOpen(false);
return (
<div>
<Button variant="destructive" onClick={handleOpen}>
Delete user data
</Button>
<AlertDialog
heading="Delete data"
isOpen={isOpen}
destructive
onConfirm={handleClose}
onConfirmLabel="Delete"
onDismiss={handleClose}
onDismissLabel="Cancel"
>
Are you sure you want to delete this data? This action cannot be undone.
</AlertDialog>
</div>
);
};
render(
<AlertDialogTrigger />
)

Opening an Alert Dialog from a Modal

Opening an Alert Dialog from a Modal page anchor
Component preview theme
const AlertDialogTrigger = () => {
const [isModalOpen, setIsModalOpen] = React.useState(false);
const [isAlertDialogOpen, setIsAlertDialogOpen] = React.useState(false);
const handleModalOpen = () => setIsModalOpen(true);
const handleModalClose = () => setIsModalOpen(false);
const handleAlertDialogOpen = () => setIsAlertDialogOpen(true);
const handleAlertDialogClose = () => setIsAlertDialogOpen(false);
const modalHeadingID = useUID();
return (
<div>
<Button variant="primary" onClick={handleModalOpen}>
Open modal
</Button>
<Modal ariaLabelledby={modalHeadingID} isOpen={isModalOpen} onDismiss={handleModalClose} size="default">
<ModalHeader>
<ModalHeading as="h3" id={modalHeadingID}>
Modal heading
</ModalHeading>
</ModalHeader>
<ModalBody>
<Heading as="h2" variant="heading40">
Open alert dialog
</Heading>
<Paragraph>Click the submit button to open the alert dialog.</Paragraph>
</ModalBody>
<ModalFooter>
<ModalFooterActions>
<Button variant="secondary" onClick={handleModalClose}>
Cancel
</Button>
<Button variant="primary" onClick={handleAlertDialogOpen}>
Submit
</Button>
</ModalFooterActions>
</ModalFooter>
</Modal>
<AlertDialog
heading="Submit application"
isOpen={isAlertDialogOpen}
onConfirm={handleAlertDialogClose}
onConfirmLabel="Submit"
onDismiss={handleAlertDialogClose}
onDismissLabel="Cancel"
>
Are you sure you want to submit this application? No information can be changed after submitting.
</AlertDialog>
</div>
);
};
render(
<AlertDialogTrigger />
)