Alerts

This page covers two related but distinct components. Alert is a static, inline banner that communicates a message in the flow of the page (a heads-up, a warning, an error summary) without interrupting the user. AlertDialog is a modal confirmation window that stops everything until the user explicitly confirms or cancels, built for consequential or destructive actions. Use the banner to inform; use the dialog to gate.

Live demo

The interactive story below runs from the deployed Storybook. It shows the static Alert banner.

Source: alert.tsx

A self-contained banner with a role="alert", a title, and a description. It supports two variants.

import { Alert, AlertTitle, AlertDescription } from "@beacon/design-system";

<Alert>
  <AlertTitle>Heads up!</AlertTitle>
  <AlertDescription>
    You can add components and dependencies to your app using the CLI.
  </AlertDescription>
</Alert>

<Alert variant="destructive">
  <AlertTitle>Error</AlertTitle>
  <AlertDescription>Your session has expired. Please log in again.</AlertDescription>
</Alert>

Alert parts

Part	Role
`Alert`	The banner container. Accepts a `variant` prop. Renders any leading `svg` icon in the top-left.
`AlertTitle`	Short heading line.
`AlertDescription`	Supporting message text.

`variant` values

Value	Meaning
`default`	Neutral informational message (default).
`destructive`	Error or failure styled with the destructive color.

AlertDialog (blocking confirmation)

Source: alert-dialog.tsx

A modal window that interrupts the page and forces an explicit choice. It is the right tool for “Are you sure?” on a destructive or irreversible action.

import {
  AlertDialog,
  AlertDialogTrigger,
  AlertDialogContent,
  AlertDialogHeader,
  AlertDialogTitle,
  AlertDialogDescription,
  AlertDialogFooter,
  AlertDialogCancel,
  AlertDialogAction,
  Button,
} from "@beacon/design-system";

<AlertDialog>
  <AlertDialogTrigger asChild>
    <Button variant="outline">Delete account</Button>
  </AlertDialogTrigger>
  <AlertDialogContent>
    <AlertDialogHeader>
      <AlertDialogTitle>Are you absolutely sure?</AlertDialogTitle>
      <AlertDialogDescription>
        This action cannot be undone. This will permanently delete your account.
      </AlertDialogDescription>
    </AlertDialogHeader>
    <AlertDialogFooter>
      <AlertDialogCancel>Cancel</AlertDialogCancel>
      <AlertDialogAction>Continue</AlertDialogAction>
    </AlertDialogFooter>
  </AlertDialogContent>
</AlertDialog>

AlertDialog parts

Part	Role
`AlertDialog`	Root state container. Accepts `open` and `onOpenChange` for controlled use.
`AlertDialogTrigger`	Element that opens the dialog. Use `asChild` to wrap your own button.
`AlertDialogContent`	The centered modal surface; renders the overlay automatically.
`AlertDialogHeader`	Layout wrapper for the title and description.
`AlertDialogTitle`	Accessible heading announced to screen readers.
`AlertDialogDescription`	Supporting text explaining the consequence.
`AlertDialogFooter`	Action row holding the cancel and confirm controls.
`AlertDialogAction`	The confirm button, styled as a primary action.
`AlertDialogCancel`	The dismiss button, styled as an outline action.
`AlertDialogPortal`	Renders content into a portal at the document root.
`AlertDialogOverlay`	The backdrop scrim. Included automatically by `AlertDialogContent`.

When to use

Use Alert for inline, non-blocking status: a warning at the top of a form, an error summary, an informational note.
Use AlertDialog to confirm a destructive or irreversible action before it runs.

Do not use a static Alert to gate a dangerous action: it does not block, so the user can ignore it. Use AlertDialog. Conversely, do not use AlertDialog for a general form or non-consequential task: that belongs in a Dialog.