Alert dialog usage guidelines

Alert dialog is the most disruptive and urgent messaging component, appearing as an overlay that interrupts user activity and requires an immediate user action.

When to use

• For critical errors that halt user progress and require immediate resolution.
• To confirm destructive or irreversible actions (for example, deleting a resource).
• To prompt users for an immediate decision that impacts their workflow significantly.
• When the user must choose between specific actions (for example, “Save changes,” “Discard changes”).
• Alert dialogs should be used sparingly for only the most important notifications as they heavily disrupt user flows.

When not to use

• Use an alert for persistent messages that need to remain visible until addressed.
• Use a toast for low-importance feedback messages that do not need to be addressed by the user.
• Use a callout for proactive, general announcements or updates that are not triggered by a specific user action.

Properties

Tone

Preview

SuccessInfoWarningCritical

Press the buttons to make the alert dialogs appear.

Code

import { AlertDialog, AlertDialogActions, AlertDialogBody, Button, DialogRoot, Stack, Text } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <Stack gap={16}>
      <Stack gap={16} direction="horizontal" wrap>
        <DialogRoot>
          <Button>Success</Button>
          <AlertDialog title="Success alert dialog" tone="success">
            {({ close }) => (
              <>
                <AlertDialogBody>This is a success alert dialog.</AlertDialogBody>
                <AlertDialogActions>
                  <Button variant="primary" onPress={close}>
                    Confirm
                  </Button>
                </AlertDialogActions>
              </>
            )}
          </AlertDialog>
        </DialogRoot>

        <DialogRoot>
          <Button>Info</Button>
          <AlertDialog title="Info alert dialog" tone="info">
            {({ close }) => (
              <>
                <AlertDialogBody>This is an info alert dialog.</AlertDialogBody>
                <AlertDialogActions>
                  <Button variant="primary" onPress={close}>
                    Confirm
                  </Button>
                </AlertDialogActions>
              </>
            )}
          </AlertDialog>
        </DialogRoot>

        <DialogRoot>
          <Button>Warning</Button>
          <AlertDialog title="Warning alert dialog" tone="warning">
            {({ close }) => (
              <>
                <AlertDialogBody>This is a warning alert dialog.</AlertDialogBody>
                <AlertDialogActions>
                  <Button variant="primary" onPress={close}>
                    Confirm
                  </Button>
                </AlertDialogActions>
              </>
            )}
          </AlertDialog>
        </DialogRoot>

        <DialogRoot>
          <Button>Critical</Button>
          <AlertDialog title="Critical alert dialog" tone="critical">
            {({ close }) => (
              <>
                <AlertDialogBody>This is a critical alert dialog.</AlertDialogBody>
                <AlertDialogActions>
                  <Button variant="primary" tone="critical" onPress={close}>
                    Confirm
                  </Button>
                </AlertDialogActions>
              </>
            )}
          </AlertDialog>
        </DialogRoot>
      </Stack>

      <Text as="p" variant="medium">
        Press the buttons to make the alert dialogs appear.
      </Text>
    </Stack>
  );
}

Copy code Open in playground

Value	Use cases
Success	Used for confirmation of successful actions, processes, and positive outcomes.
Info	Used for important details without implying positivity or negativity.
Warning	Used for non-critical issues, potential problems that won’t block user progress, and recommendations for attention.
Critical	Used for critical issues that will block user progress or otherwise need to be addressed.

Formatting and layout

Placement

Alert dialogs are notification-specific modal dialogs, and they should follow the same placement as other modal dialogs. They are centered on the screen, they overlay all other page content, and they are placed on top of a darkened overlay, forcing user attention to be on the alert dialog. Users cannot return to any other page content until they take action in the alert dialog.

Actions

Alert dialogs must contain at least one action for the user to take. These actions are displayed at the bottom of the alert dialog.

If there is a suggested best course of action, or an action that the user is expected to take (for example, “Delete” in a delete confirmation modal), that action should be rendered using a primary button. In the case of equal actions (for example, “Replace”, “Keep Both”, and “Abort” when copying files), all actions should be rendered using secondary buttons.

In alert dialogs that use the critical tone, the primary action button should also use the critical tone.

Preview

Open dialog

Press the button to make the alert dialog appear.

Code

import { AlertDialog, AlertDialogActions, AlertDialogBody, Button, DialogRoot, Stack, Text } from '@cimpress-ui/react';

export default function Demo() {
  return (
    <Stack gap={16}>
      <DialogRoot>
        <Button>Open dialog</Button>
        <AlertDialog title="Confirm deletion" tone="critical">
          {({ close }) => (
            <>
              <AlertDialogBody>
                <Text as="p">Are you sure you want to delete this file?</Text>
                <Text as="p" tone="subtle" marginTop={8}>
                  (Actions taken in this example alert dialog will have no effect.)
                </Text>
              </AlertDialogBody>
              <AlertDialogActions>
                <Button onPress={close}>Cancel</Button>
                <Button variant="primary" tone="critical" onPress={close}>
                  Delete
                </Button>
              </AlertDialogActions>
            </>
          )}
        </AlertDialog>
      </DialogRoot>

      <Text as="p" variant="medium">
        Press the button to make the alert dialog appear.
      </Text>
    </Stack>
  );
}

Copy code Open in playground

Content writing

Title

• Give users a concise, clear overview of the situation or the user action that’s needed.

Message body

• Explain the situation clearly.
• Specify what action is required, and any outcomes that users should expect from taking the available actions.
• Keep the message as brief as possible while providing necessary context.

Action buttons

• Use clear labels for buttons (for example, “Delete”, “Confirm”, or “Cancel”).
• The primary action should be the action the user is expecting to take (“Delete” in a delete confirmation modal) or the action that’s the suggested best course of action.
• In the case of equal actions (for example, “Replace”, “Keep Both”, and “Abort” when copying files) use secondary buttons for all actions.

Behaviors

Dismissing alert dialogs

Alert dialogs can only be dismissed by taking action with the buttons in the dialog. Users cannot otherwise return to the page they were working in and cannot take any other actions.