AlertDialog

Playground

Installation

pnpm add @tessinaui/ui

Usage

import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogBody,
  AlertDialogFooter,
  AlertDialogAction,
  AlertDialogCancel,
} from "@tessinaui/ui";

<AlertDialog intent="error">
  <AlertDialogTrigger render={<Button intent="error">Delete</Button>} />
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Delete this project?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Delete</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

Examples

Default

A destructive confirmation with the error intent and an icon trigger.

Intents

intent drives the header icon and the default action-button colour — error, warning, success, and info.

Sizes

Four max-widths — sm, md, lg, and xl — to fit the message length.

Footer layout

AlertDialogFooter lays buttons out as an end-aligned row or a full-width stacked column.

Intent border

Opt in to a colour-matched popup border with showIntentBorder.

Loading

AlertDialogSkeleton mirrors the popup shape while content loads.

When to use AlertDialog vs. Modal vs. Alert

Anatomy

<AlertDialog>
  <AlertDialogTrigger>…</AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle />
      <AlertDialogDescription />
    </AlertDialogHeader>
    <AlertDialogBody />        {/* optional */}
    <AlertDialogFooter>
      <AlertDialogCancel />
      <AlertDialogAction />
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

AlertDialogHeader automatically renders the icon for the current intent (or your custom icon). AlertDialogAction is intent-aware — it inherits the dialog's intent so destructive confirmations are coloured correctly without extra props.

Size

Intent

intent drives the header icon (auto) and the default colour of AlertDialogAction. The popup border stays neutral by default — opt in to a coloured border with showIntentBorder when the surrounding context doesn't already convey urgency.

Rounded

Footer layout

AlertDialogFooter accepts layout:

• "row" (default) — horizontal, end-aligned. Standard desktop pattern.
• "stacked" — full-width buttons stacked vertically. iOS / mobile style.

<AlertDialogFooter layout="stacked">
  <AlertDialogAction>Power off</AlertDialogAction>
  <AlertDialogCancel>Cancel</AlertDialogCancel>
</AlertDialogFooter>

When layout="stacked", place AlertDialogAction first — flex-col-reverse puts it on top so the destructive action sits closest to the title.

Dismissal behaviour

Unlike Modal, the alert dialog cannot be dismissed by:

• Clicking outside the popup
• Pressing Escape

The user must choose AlertDialogAction, AlertDialogCancel, or your own AlertDialogClose. This is the W3C-recommended pattern for role="alertdialog".

Controlled

const [open, setOpen] = React.useState(false);

<AlertDialog open={open} onOpenChange={setOpen}>
  …
</AlertDialog>

Custom action via AlertDialogClose

When you need full control over the button (e.g., async confirmation, loading state), use AlertDialogClose directly with render:

<AlertDialogClose
  render={
    <Button onClick={async () => {
      await deleteProject();
      // dialog closes automatically after the click handler resolves
    }}>
      Delete forever
    </Button>
  }
/>

Accessibility

• Renders with role="alertdialog" so screen readers treat it as a critical interruption.
• AlertDialogTitle is wired to aria-labelledby, AlertDialogDescription to aria-describedby.
• Focus traps inside the popup. On open, focus moves to the first focusable element (typically AlertDialogCancel).
• On close, focus returns to the trigger.
• The popup is not dismissible by outside click or Escape — both gestures are intentionally swallowed.
• Use intent="error" for destructive confirmations; the semantic colour, header icon, and action button intent all update so assistive tech and sighted users get the same signal.

RTL

Pass dir="rtl" to the root. The header icon, title, footer button order, and stacked layout all follow the reading direction.

<AlertDialog dir="rtl" intent="error">
  <AlertDialogTrigger render={<Button intent="error">حذف</Button>} />
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>هل أنت متأكد من الحذف؟</AlertDialogTitle>
      <AlertDialogDescription>لا يمكن التراجع عن هذا الإجراء.</AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>إلغاء</AlertDialogCancel>
      <AlertDialogAction>حذف</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

API Reference

AlertDialog (root)

AlertDialogContent

Inherits size, rounded, intent, and dir from the root. Override any of them to scope the popup independently.

AlertDialogHeader

AlertDialogFooter

AlertDialogAction, AlertDialogCancel

Both render a Button. Pass any Button prop (size, rounded, loading, leadingIcon, etc.). Both auto-close the dialog on click.

• AlertDialogAction defaults to variant="primary" and inherits the dialog's intent.
• AlertDialogCancel defaults to variant="outline" and intent="none".

AlertDialogTrigger, AlertDialogClose

Render a <button>. Use render={<CustomElement />} to swap in a Button or any element. Standard Base UI render-prop pattern.

Sub-components

AlertDialogTitle, AlertDialogDescription, AlertDialogBody, AlertDialogBackdrop — all accept className and any HTML props.

Notes

• Built on @base-ui/react/alert-dialog, with W3C role="alertdialog" semantics.
• The popup uses Base UI's data-[starting-style] and data-[ending-style] attributes for entry/exit animation.
• The header icon background tints automatically per intent (bg-error-light etc.) for a soft callout.