Alert Dialog

A confirmation modal for decisions that require explicit acknowledgement.

Default

A decision that must be acknowledged before work continues. The footer defaults to layout="equal", so the two actions share the width.

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

export default function AlertDialogDefault() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button variant="secondary" />}>Adjust CPS</AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogBody>
          <AlertDialogHeader>
            <AlertDialogTitle>Adjust CPS</AlertDialogTitle>
            <AlertDialogDescription>
              This is a rented number, so its calls per second are set by our telephony providers. To change it,
              contact our support team.
            </AlertDialogDescription>
          </AlertDialogHeader>
        </AlertDialogBody>
        <AlertDialogFooter>
          <AlertDialogCancel render={<Button variant="secondary" />}>Cancel</AlertDialogCancel>
          <AlertDialogAction render={<Button />}>Contact support</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}

Destructive

Add AlertDialogIcon and pass layout="end" to right-align the actions. Name the object in the title and the action.

import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogBody,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogIcon,
  AlertDialogTitle,
  AlertDialogTrigger,
  Button,
  TriangleAlertIcon,
} from "@smallest-inc/ui";

export default function AlertDialogDestructive() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button variant="danger" />}>Delete agent</AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogBody>
          <AlertDialogIcon>
            <TriangleAlertIcon radius="2" />
          </AlertDialogIcon>
          <AlertDialogHeader>
            <AlertDialogTitle>Delete Support agent?</AlertDialogTitle>
            <AlertDialogDescription>
              The agent, its prompt and its call history will be permanently deleted. This cannot be undone.
            </AlertDialogDescription>
          </AlertDialogHeader>
        </AlertDialogBody>
        <AlertDialogFooter layout="end">
          <AlertDialogCancel render={<Button variant="secondary" />}>Cancel</AlertDialogCancel>
          <AlertDialogAction render={<Button variant="danger" />}>Delete agent</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}

Controlled

Pass open and onOpenChange to raise the alert from code, such as when someone leaves a page with unsaved changes.

import { useState } from "react";
import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogBody,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogTitle,
  Button,
} from "@smallest-inc/ui";

export default function AlertDialogControlled() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>
        Leave editor
      </Button>
      <AlertDialog open={open} onOpenChange={setOpen}>
        <AlertDialogContent>
          <AlertDialogBody>
            <AlertDialogHeader>
              <AlertDialogTitle>Discard prompt changes?</AlertDialogTitle>
              <AlertDialogDescription>
                You have unsaved edits to the Support agent prompt. Leaving now discards them.
              </AlertDialogDescription>
            </AlertDialogHeader>
          </AlertDialogBody>
          <AlertDialogFooter>
            <AlertDialogCancel render={<Button variant="secondary" />}>Keep editing</AlertDialogCancel>
            <AlertDialogAction render={<Button />}>Discard changes</AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
    </>
  );
}

Best practices

When to use

Use for a consequential decision that must be acknowledged before work continues: deleting an agent, discarding unsaved prompt changes.
Use Dialog when the decision needs fields, and Toast with Undo when the action is easily reversible.

Behavior

The footer defaults to layout="equal" (actions share the width). Use layout="end" with AlertDialogIcon for destructive confirmations.
Clicking the overlay or pressing Escape dismisses the alert, the same as Cancel.
Pass open and onOpenChange to raise the alert from code, such as a navigation guard.

Content

Use a sentence-case title that names the object, often as a question: “Delete Support agent?”. The primary action repeats the verb: “Delete agent”, never “OK” or “Confirm”.
Keep the dismissal action “Cancel”, or a specific alternative such as “Keep editing”. Say in the description what is lost and that it cannot be undone.

Accessibility

Render actions with AlertDialogCancel and AlertDialogAction so both close the alert and focus returns to the trigger.

PreviousAccordion NextAperture