Alert

A block in the page, tinted by its meaning, that states a condition and what to do about it.

ui.alertcomponents/ui/alert.tsx

Use case

For the AI

Use an alert for something true while the page is open: a client's site is down, a certificate runs out in 9 days, the bank connection needs reconnecting, this invoice is overdue. It sits where the problem is, at the top of the page or of the card it concerns, and stays until the condition changes. Its AlertAction holds the one button that fixes or opens it.

Use it when

A problem with the record on screen (overdue, blocked, down)
A warning about something coming (a renewal, an expiry)
A note that explains how the page behaves (backups run nightly)
A good state worth stating (everything is up)

Use something else when

Saying an action just finished: Toast
Stopping the person to confirm a destructive action: Alert dialog and confirm
A one-word status in a list: Badge
A place with nothing in it yet: Empty state

Examples

Backups run every night

The last one finished at 3:12 and took 4 minutes.

Everything is up

99.98% this month.

The certificate runs out in 9 days

Vercel renews it on its own; nothing to do unless it fails.

The site is down

Since 2:04 p.m., from every region.

Code

Import

import { OctagonAlertIcon } from "@/components/icons"
import { Alert, AlertAction, AlertDescription, AlertTitle } from "@/components/ui/alert"
import { Button } from "@/components/ui/button"

Usage

export function SiteDown({ since }: { since: string }) {
  return (
    <Alert variant="error">
      <OctagonAlertIcon />
      <AlertTitle>The site is down</AlertTitle>
      <AlertDescription>Since {since}, from every region.</AlertDescription>
      <AlertAction>
        <Button size="sm" variant="destructive">
          Open It
        </Button>
      </AlertAction>
    </Alert>
  )
}

Rules

The variant matches the meaning and its icon: default or info (InfoIcon), success (CheckCircle2Icon), warning (AlertTriangleIcon), error (OctagonAlertIcon).
Order: the icon as the first child, then AlertTitle, AlertDescription and AlertAction. The title is one short sentence, the description the detail.
One action at most, size sm; on an error alert it is the destructive button.
With a title the action spans both lines; a one-line alert with an action centres the icon, the words and the button on one line.
Alert carries role="alert", so a screen reader announces it when it appears: keep it for what matters.