AlertDialog

A focused modal that interrupts the user to confirm a single action — usually a destructive one like cancelling a shipment or deleting a label. Built on base-ui Alert Dialog — focus is trapped, the action is announced as an alert, and the dialog can’t be dismissed by clicking the backdrop or pressing Escape. The only ways out are the explicit Cancel and Action buttons.

That last part is the difference from Dialog: a Dialog is a general container (forms, detail panels, multi-step flows) and is casually dismissable. Reach for AlertDialog only when you need a deliberate yes/no decision before something irreversible happens.

Compose the parts: AlertDialog (root, owns open state), AlertDialogTrigger (opens it), AlertDialogContent (the popup, renders its own backdrop), AlertDialogHeader wrapping AlertDialogTitle + AlertDialogDescription, and AlertDialogFooter holding AlertDialogCancel and AlertDialogAction. Per house convention, Cancel sits on the left and the primary/destructive action on the right.

Default

A trigger opens the dialog; the footer pairs AlertDialogCancel (defaults to the outline button variant) with a destructive AlertDialogAction. Wrap a Button in the trigger’s render prop so it inherits the styling you want.

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

export default function AlertDialogDefault() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button variant="destructive" />}>
        Cancel shipment
      </AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Cancel shipment?</AlertDialogTitle>
          <AlertDialogDescription>
            The label for order #1042 will be voided and the carrier pickup released. This can't be
            undone — you'll need to buy a new label to ship again.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Keep shipment</AlertDialogCancel>
          <AlertDialogAction variant="destructive">Cancel shipment</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}

Non-destructive confirm

Not every confirmation is a deletion. Drop the variant="destructive" on AlertDialogAction and it falls back to the primary button — right for a benign-but-consequential step like notifying a customer.

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

export default function AlertDialogConfirm() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button />}>Mark as shipped</AlertDialogTrigger>
      <AlertDialogContent>
        <AlertDialogHeader>
          <AlertDialogTitle>Mark order as shipped?</AlertDialogTitle>
          <AlertDialogDescription>
            The customer will be notified with tracking details for order #1042. You can still add
            packages to this shipment afterward.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Not yet</AlertDialogCancel>
          <AlertDialogAction>Mark as shipped</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}

Controlled with a pending action

Drive the dialog yourself with open / onOpenChange when the confirm fires an async mutation. Call e.preventDefault() in the action’s onClick so the dialog stays open while the request runs, set loading on the action for the spinner, and disabled on Cancel — then close in onOpenChange once the work resolves.

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

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

  const handleConfirm = () => {
    setDeleting(true);
    // Stand in for a real mutation — keep the dialog open and the spinner up.
    setTimeout(() => {
      setDeleting(false);
      setOpen(false);
    }, 1500);
  };

  return (
    <>
      <Button variant="destructive" onClick={() => setOpen(true)}>
        Delete label
      </Button>
      <AlertDialog open={open} onOpenChange={setOpen}>
        <AlertDialogContent>
          <AlertDialogHeader>
            <AlertDialogTitle>Delete label?</AlertDialogTitle>
            <AlertDialogDescription>
              The shipping label and its tracking number will be permanently removed. Any pending
              carrier scans will stop reporting to the customer.
            </AlertDialogDescription>
          </AlertDialogHeader>
          <AlertDialogFooter>
            <AlertDialogCancel disabled={deleting}>Cancel</AlertDialogCancel>
            <AlertDialogAction
              variant="destructive"
              loading={deleting}
              onClick={(e) => {
                e.preventDefault();
                handleConfirm();
              }}
            >
              Delete label
            </AlertDialogAction>
          </AlertDialogFooter>
        </AlertDialogContent>
      </AlertDialog>
    </>
  );
}

With media

AlertDialogMedia renders a rounded badge above the title that auto-sizes its svg child. Use it for high-stakes confirmations where a warning icon adds weight; pair it with size="sm" on AlertDialogContent for the centered, two-column-footer layout.

import {
  AlertDialog,
  AlertDialogAction,
  AlertDialogCancel,
  AlertDialogContent,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogHeader,
  AlertDialogMedia,
  AlertDialogTitle,
  AlertDialogTrigger,
  Button,
} from "@vesyl/ui-next";
import { TriangleAlert } from "lucide-react";

export default function AlertDialogMediaDemo() {
  return (
    <AlertDialog>
      <AlertDialogTrigger render={<Button variant="destructive" />}>
        Void manifest
      </AlertDialogTrigger>
      <AlertDialogContent size="sm">
        <AlertDialogHeader>
          <AlertDialogMedia className="bg-destructive/10 text-destructive">
            <TriangleAlert />
          </AlertDialogMedia>
          <AlertDialogTitle>Void end-of-day manifest?</AlertDialogTitle>
          <AlertDialogDescription>
            All 38 labels on today's manifest will be voided and removed from carrier pickup. This
            can't be undone.
          </AlertDialogDescription>
        </AlertDialogHeader>
        <AlertDialogFooter>
          <AlertDialogCancel>Keep manifest</AlertDialogCancel>
          <AlertDialogAction variant="destructive">Void manifest</AlertDialogAction>
        </AlertDialogFooter>
      </AlertDialogContent>
    </AlertDialog>
  );
}

Reference

AlertDialog

Root container. Owns open state. Extends base-ui AlertDialog.Root props.

Prop	Type	Default	Description
`defaultOpen`	`boolean`	`false`	Initial open state (uncontrolled)
`open`	`boolean`	—	Open state (controlled)
`onOpenChange`	`(open: boolean) => void`	—	Fires when the dialog opens or closes

AlertDialogTrigger

The control that opens the dialog. Extends base-ui AlertDialog.Trigger props.

Prop	Type	Default	Description
`render`	`ReactElement`	—	Element to render as the trigger, e.g. `<Button variant="…" />`

AlertDialogContent

The popup. Renders its own portal and backdrop, so you don’t compose those yourself. Extends base-ui AlertDialog.Popup props.

Prop	Type	Default	Description
`size`	`"sm" \| "md"`	`"md"`	`md` left-aligns at width; `sm` centers and stacks the footer 2-up
`showBackdrop`	`boolean`	`true`	Render the dimming overlay; set `false` for a dialog nested in another
`className`	`string`	—	Merged onto the popup

AlertDialogHeader

Layout wrapper for the title and description (and optional media). Plain div — accepts standard div props plus className.

AlertDialogTitle

The heading, announced to assistive tech. Extends base-ui AlertDialog.Title props. Required for accessibility.

AlertDialogDescription

Supporting copy under the title. Extends base-ui AlertDialog.Description props. Anchor tags inside it are auto-underlined.

AlertDialogMedia

Optional rounded icon badge shown above the title. Plain div; auto-sizes a child svg to size-8. Pass a className to tint it (e.g. bg-destructive/10 text-destructive).

AlertDialogFooter

Action row. Plain div — column-reversed on mobile, right-aligned row on desktop. Place AlertDialogCancel first (left) and AlertDialogAction last (right).

AlertDialogAction

The confirm button. Wraps Button and accepts all its props.

Prop	Type	Default	Description
`variant`	`"default" \| "destructive" \| "outline" \| "secondary" \| "ghost" \| "link"`	`"default"`	Use `"destructive"` for irreversible actions
`loading`	`boolean`	`false`	Shows a spinner and disables the button

Does not auto-close on click in itself — closing is governed by the dialog’s open state. For a synchronous confirm, leave it; for an async one, preventDefault and close via onOpenChange.

AlertDialogCancel

The dismiss button. Wraps base-ui AlertDialog.Close rendered as a Button — closing the dialog on click is automatic.

Prop	Type	Default	Description
`variant`	same as `Button`	`"outline"`	Button styling for the cancel action
`size`	same as `Button`	`"md"`	Button size