Alert Dialog

Anatomy

import {AlertDialog} from '@staffbase/design';

<AlertDialog.Root>
  <AlertDialog.Trigger />
  <AlertDialog.Popup>
    <AlertDialog.Icon />
    <AlertDialog.Title />
    <AlertDialog.Description />
    <AlertDialog.Action />
    <AlertDialog.Cancel />
  </AlertDialog.Popup>
</AlertDialog.Root>

API reference

Root

Trigger

Popup

Icon

Title

Renders an <h2> element.

Description

Renders a <p> element.

Action

Cancel

When to use

• To confirm a destructive action that cannot be undone, such as deleting or removing an item.
• To confirm a major action with big consequences, such as sending an email to many recipients.
• When the user must explicitly confirm or cancel before anything happens — the alert dialog blocks interaction with the page until a choice is made.

When not to use

• Don’t use an alert dialog for a focused task, form input, or content that needs more than a confirm/cancel choice — use Dialog instead.
• Don’t use an alert dialog to announce non-blocking information, success, or system status — use Banner instead.
• Don’t use an alert dialog for lightweight contextual content anchored to its trigger — use Popover instead.
• Don’t use an alert dialog for actions that are easily reversible — perform the action directly and offer an undo option.

How to use

Structure

• Compose every alert dialog from an optional icon at the top, a title, a description, an action button, and a Cancel button below it.
• Keep the content to a single confirm-or-cancel decision — never add form fields, links, or extra actions.
• The popup is 296px wide (max-width 100vw minus 80px on small screens), with the icon, title, and description centered and the buttons stacked full-width.

Icon

• The icon is optional — use it to reinforce the action type or urgency level.
• Only use an icon that is simple and universally recognized, such as a bin icon for deletion.

Buttons

• Use color="critical" on the action button for destructive actions such as deleting or removing items.
• Use the default color="primary" on the action button for major, non-destructive actions such as sending or publishing.
• Always keep the Cancel button below the action button — it closes the dialog without performing the action.

Behavior

• The alert dialog always renders above a backdrop that dims the page, keeping the dialog the sole focus of interaction.
• Don’t attach custom dismissal to the backdrop — the user must choose the action or Cancel.

Accessibility

• Always provide an AlertDialog.Title — it labels the dialog for assistive technology.
• Always provide an AlertDialog.Description explaining the consequences — it is announced to screen reader users.
• The trigger must be a button element so the dialog can be opened with the keyboard.
• Focus is trapped inside the dialog while it is open and returns to the trigger when it closes.

Content & UX copy

• Phrase the title as a question in sentence case, ending with a question mark, in verb + noun format, such as “Delete space?”.
• Don’t use “Cancel” as the verb in the title — it collides with the Cancel button label.
• Write the description in sentence case, ending with a period, with a short explanation of the consequences.
• Add a second description sentence to explain how to reverse the action, if it is reversible.
• Don’t use exclamation points in the title or description.
• Label buttons in Title Case following the button labeling rules.
• Repeat the verb from the title on the action button, such as Delete or Send — never vague labels like Yes or OK.
• Label the cancel button “Cancel”.